OneSignal-Capacitor-SDK

The pure Capacitor plugin for OneSignal, providing push notifications, in-app messaging, live activities, and more.

Install

Install with your package manager of choice:

# with vp
vp add @onesignal/capacitor-plugin

# with bun
bun add @onesignal/capacitor-plugin

# with npm
npm install @onesignal/capacitor-plugin

Then sync Capacitor:

# with vp
vpx cap sync

# with bun
bunx cap sync

# with npm
npx cap sync

Disabling OneSignal Location

If your app does not use OneSignal.Location, you can exclude the native OneSignal location module from iOS and Android builds.

Set ONESIGNAL_DISABLE_LOCATION=true in the environment before resolving or building native dependencies. The value is case-insensitive, and 1 is also accepted.

ONESIGNAL_DISABLE_LOCATION=true npx cap sync

For day-to-day native builds and runs, keep the same environment variable set so Capacitor, Swift Package Manager, CocoaPods, and Gradle do not re-resolve with the location module included:

ONESIGNAL_DISABLE_LOCATION=true npx cap run ios
ONESIGNAL_DISABLE_LOCATION=true npx cap run android

In GitHub Actions, set it once at the job or step level so Swift Package Manager, CocoaPods, and Gradle builds inherit it:

env:
  ONESIGNAL_DISABLE_LOCATION: true

With the location module disabled, calls to OneSignal.Location are ignored on Android and OneSignal.Location.isShared() resolves false.

Applying the change

The environment variable is read when native dependencies are resolved. If you change the variable in an existing project, clear the relevant cache and re-resolve in a shell where the variable is exported.

Important

When using Xcode or Android Studio, launch the IDE from a terminal that has ONESIGNAL_DISABLE_LOCATION exported. An IDE launched from the Dock/Finder does not inherit variables set only in your shell profile.

Swift Package Manager:

rm -rf ~/Library/Caches/org.swift.swiftpm ~/Library/Developer/Xcode/DerivedData/*
ONESIGNAL_DISABLE_LOCATION=true npx cap sync ios

In Xcode, you can instead use File -> Packages -> Reset Package Caches with the variable exported, then build.

CocoaPods:

cd ios/App
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install

Android Gradle, which re-reads the variable on each configuration:

ONESIGNAL_DISABLE_LOCATION=true npx cap sync android
cd android
ONESIGNAL_DISABLE_LOCATION=true ./gradlew assembleDebug

On CI, key any DerivedData, SwiftPM, CocoaPods, or Gradle caches on the value of ONESIGNAL_DISABLE_LOCATION so a restored cache does not resurrect the location module.

Usage

import OneSignal from '@onesignal/capacitor-plugin';

await OneSignal.initialize({ appId: 'YOUR_ONESIGNAL_APP_ID' });
await OneSignal.Notifications.requestPermission(true);

See the examples/demo directory for a full working example.

API

• initialize(...)
• login(...)
• logout()
• setConsentRequired(...)
• setConsentGiven(...)
• Interfaces
• Type Aliases

The public OneSignal Capacitor plugin API. This is the shape of the default OneSignal export.

initialize(...)

initialize(appId: string) => Promise<void>

Initialize the SDK with your OneSignal app ID. Call during app startup.

Param	Type
appId	string

---

login(...)

login(externalId: string) => Promise<void>

Log in to OneSignal as the user identified by externalId, switching the user context.

Param	Type
externalId	string

---

logout()

logout() => Promise<void>

Log out the current user. The SDK will reference a new device-scoped user.

---

setConsentRequired(...)

setConsentRequired(required: boolean) => void

Set whether user privacy consent is required before sending data to OneSignal. Call before initialize.

Param	Type
required	boolean

---

setConsentGiven(...)

setConsentGiven(granted: boolean) => void

Indicate whether the user has granted privacy consent.

Param	Type
granted	boolean

---

Interfaces

OneSignalDebugAPI

Debug helpers exposed via OneSignal.Debug.

Method	Signature	Description
setLogLevel	(logLevel: LogLevel) => void	Set the log level printed to LogCat (Android) or the Xcode console (iOS).
setAlertLevel	(visualLogLevel: LogLevel) => void	Set the log level shown to the user as alert dialogs.

OneSignalUserAPI

Current-user operations exposed via OneSignal.User.

Prop	Type	Description
pushSubscription	OneSignalPushSubscriptionAPI	Push subscription controls for the current user.

Method	Signature	Description
setLanguage	(language: string) => Promise<void>	Explicitly set a 2-character language code for the current user.
addAlias	(label: string, id: string) => Promise<void>	Add or overwrite a single alias on the current user.
addAliases	(aliases: Record<string, string>) => Promise<void>	Add or overwrite multiple aliases on the current user.
removeAlias	(label: string) => Promise<void>	Remove a single alias by label from the current user.
removeAliases	(labels: string[]) => Promise<void>	Remove multiple aliases by label from the current user.
addEmail	(email: string) => Promise<void>	Add a new email subscription to the current user.
removeEmail	(email: string) => Promise<void>	Remove an email subscription from the current user.
addSms	(smsNumber: string) => Promise<void>	Add a new SMS subscription to the current user.
removeSms	(smsNumber: string) => Promise<void>	Remove an SMS subscription from the current user.
addTag	(key: string, value: string) => Promise<void>	Add a single tag (key/value) on the current user, used for targeting and personalization.
addTags	(tags: object) => Promise<void>	Add or overwrite multiple tags on the current user.
removeTag	(key: string) => Promise<void>	Remove a single tag by key from the current user.
removeTags	(keys: string[]) => Promise<void>	Remove multiple tags by key from the current user.
getTags	() => Promise<{ [key: string]: string; }>	Get the local tags for the current user.
addEventListener	(event: 'change', listener: (event: UserChangedState) => void) => void	Add a listener for OneSignal user state changes.
removeEventListener	(event: 'change', listener: (event: UserChangedState) => void) => void	Remove a previously added user state listener.
getOnesignalId	() => Promise<string | null>	Get the OneSignal-assigned ID for the current user, or null if not yet available.
getExternalId	() => Promise<string | null>	Get the external ID set via login, or null if the user is anonymous.
trackEvent	(name: string, properties?: object | undefined) => Promise<void>	Track a custom event with an optional set of JSON-serializable properties.

UserChangedState

Prop	Type
current	UserState

UserState

Prop	Type
onesignalId	string
externalId	string

OneSignalPushSubscriptionAPI

Push subscription state and controls exposed via OneSignal.User.pushSubscription.

Method	Signature	Description
getIdAsync	() => Promise<string | null>	Get the current device's push subscription ID, or null if not yet assigned.
getTokenAsync	() => Promise<string | null>	Get the current device's push token, or null if not yet available.
getOptedInAsync	() => Promise<boolean>	Whether the current user is opted in to push notifications. Returns true when the app has notification permission and optOut() has not been called. Does not guarantee a token has been received.
addEventListener	(event: 'change', listener: (event: PushSubscriptionChangedState) => void) => void	Add a listener for push subscription state changes.
removeEventListener	(event: 'change', listener: (event: PushSubscriptionChangedState) => void) => void	Remove a previously added push subscription state listener.
optIn	() => Promise<void>	Opt the user in to push notifications. Prompts for permission if needed.
optOut	() => Promise<void>	Opt the user out of push notifications on this device.

PushSubscriptionChangedState

Prop	Type
previous	PushSubscriptionState
current	PushSubscriptionState

PushSubscriptionState

Prop	Type
id	string
token	string
optedIn	boolean

OneSignalNotificationsAPI

Notification permission and event handling exposed via OneSignal.Notifications.

Method	Signature	Description
hasPermission	() => Promise<boolean>	Whether the app currently has notification permission (including provisional/ephemeral).
permissionNative	() => Promise<OSNotificationPermission>	iOS only. The native notification permission status.
requestPermission	(fallbackToSettings?: boolean | undefined) => Promise<boolean>	Prompt the user for notification permission. Optionally fall back to system settings.
canRequestPermission	() => Promise<boolean>	Whether requesting notification permission would still show a prompt.
registerForProvisionalAuthorization	(handler?: ((response: boolean) => void) | undefined) => void	iOS only. Request provisional authorization for quiet notifications without prompting.
addEventListener	<K extends NotificationEventName>(event: K, listener: (event: NotificationEventTypeMap[K]) => void) => void	Add a listener for click, foregroundWillDisplay, or permissionChange events.
removeEventListener	<K extends NotificationEventName>(event: K, listener: (obj: NotificationEventTypeMap[K]) => void) => void	Remove a previously added notification event listener.
clearAll	() => Promise<void>	Remove all OneSignal notifications from the notification center.
removeNotification	(id: number) => Promise<void>	Android only. Cancel a single notification by its Android notification ID.
removeGroupedNotifications	(id: string) => Promise<void>	Android only. Cancel a group of notifications by group key.

NotificationClickEvent

Prop	Type
result	NotificationClickResult
notification	OSNotification

NotificationClickResult

Prop	Type
actionId	string
url	string

OneSignalInAppMessagesAPI

In-app message triggers and event handling exposed via OneSignal.InAppMessages.

Method	Signature	Description
addEventListener	<K extends InAppMessageEventName>(event: K, listener: (event: InAppMessageEventTypeMap[K]) => void) => void	Add a listener for IAM click, willDisplay, didDisplay, willDismiss, or didDismiss events.
removeEventListener	<K extends InAppMessageEventName>(event: K, listener: (obj: InAppMessageEventTypeMap[K]) => void) => void	Remove a previously added IAM event listener.
addTrigger	(key: string, value: string) => Promise<void>	Add a single trigger (key/value) used to determine which IAMs are displayed to the user.
addTriggers	(triggers: { [key: string]: string; }) => Promise<void>	Add or overwrite multiple triggers for the current user.
removeTrigger	(key: string) => Promise<void>	Remove a single trigger by key.
removeTriggers	(keys: string[]) => Promise<void>	Remove multiple triggers by key.
clearTriggers	() => Promise<void>	Clear all triggers from the current user.
setPaused	(pause: boolean) => void	Pause or resume the display of in-app messages.
getPaused	() => Promise<boolean>	Whether in-app messaging is currently paused.

InAppMessageClickEvent

Prop	Type
message	OSInAppMessage
result	InAppMessageClickResult

OSInAppMessage

Prop	Type
messageId	string

InAppMessageClickResult

Prop	Type
closingMessage	boolean
actionId	string
url	string
urlTarget	InAppMessageActionUrlType

InAppMessageWillDisplayEvent

Prop	Type
message	OSInAppMessage

InAppMessageDidDisplayEvent

Prop	Type
message	OSInAppMessage

InAppMessageWillDismissEvent

Prop	Type
message	OSInAppMessage

InAppMessageDidDismissEvent

Prop	Type
message	OSInAppMessage

OneSignalSessionAPI

Outcome reporting exposed via OneSignal.Session.

Method	Signature	Description
addOutcome	(name: string) => Promise<void>	Record an outcome with the given name against the current session.
addUniqueOutcome	(name: string) => Promise<void>	Record a unique outcome with the given name against the current session.
addOutcomeWithValue	(name: string, value: number) => Promise<void>	Record an outcome with the given name and value against the current session.

OneSignalLocationAPI

Location permission and sharing exposed via OneSignal.Location.

Method	Signature	Description
requestPermission	() => Promise<void>	Prompt the user for location permission to enable geotagging.
setShared	(shared: boolean) => void	Enable or disable sharing the device location with OneSignal.
isShared	() => Promise<boolean>	Whether the device location is currently shared with OneSignal.

OneSignalLiveActivitiesAPI

Live activity controls exposed via OneSignal.LiveActivities. iOS only unless noted.

Method	Signature	Description
enter	(activityId: string, token: string, onSuccess?: ((data: unknown) => void) | undefined, onFailure?: ((data: unknown) => void) | undefined) => void	Associate a live activity ID with a push token so OneSignal can target it.
exit	(activityId: string, onSuccess?: ((data: unknown) => void) | undefined, onFailure?: ((data: unknown) => void) | undefined) => void	Disassociate a live activity ID.
setPushToStartToken	(activityType: string, token: string) => Promise<void>	Register a pushToStart token for the given live activity attributes type.
removePushToStartToken	(activityType: string) => Promise<void>	Remove a previously registered pushToStart token for the given attributes type.
setupDefault	(options?: LiveActivitySetupOptions | undefined) => Promise<void>	Set up the OneSignal default live activity, optionally enabling pushToStart/pushToUpdate.
startDefault	(activityId: string, attributes: Record<string, unknown>, content: Record<string, unknown>) => Promise<void>	Start a live activity backed by the OneSignal default attributes type.

Type Aliases

LogLevel

(typeof LogLevel)[keyof typeof LogLevel]

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

OSNotificationPermission

(typeof OSNotificationPermission)[keyof typeof OSNotificationPermission]

NotificationEventName

'click' | 'foregroundWillDisplay' | 'permissionChange'

NotificationEventTypeMap

{ click: NotificationClickEvent; foregroundWillDisplay: NotificationWillDisplayEvent; permissionChange: boolean; }

InAppMessageEventName

'click' | 'willDisplay' | 'didDisplay' | 'willDismiss' | 'didDismiss'

InAppMessageEventTypeMap

{ click: InAppMessageClickEvent; willDisplay: InAppMessageWillDisplayEvent; didDisplay: InAppMessageDidDisplayEvent; willDismiss: InAppMessageWillDismissEvent; didDismiss: InAppMessageDidDismissEvent; }

InAppMessageActionUrlType

'browser' | 'webview' | 'replacement'

LiveActivitySetupOptions

The setup options for OneSignal.LiveActivities.setupDefault.

{ /** * When true, OneSignal will listen for pushToStart tokens for the OneSignalLiveActivityAttributes structure. / enablePushToStart: boolean; /* * When true, OneSignal will listen for pushToUpdate tokens for each start live activity that uses the * OneSignalLiveActivityAttributes structure. */ enablePushToUpdate: boolean; }