OneSignal-Capacitor-SDK

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

Install

npm install @onesignal/capacitor-plugin
npx cap sync

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; }