Comprehensive API reference for the OneSignal Mobile SDK, including initialization, user identity, subscriptions, tags, permissions, in-app messages, live activities, and more. Supports Android, iOS, Unity, React Native, Flutter, and Cordova/Ionic platforms.
These methods are a reference for integrating the OneSignal SDK into your app. For full platform-specific setup instructions, see Mobile SDK setup.
initialize()
Initializes the OneSignal SDK. This should be called during application startup. The ONESIGNAL_APP_ID
can be found in Keys & IDs.
If you want to delay initialization of the OneSignal SDK, we recommend using our Privacy methods.
setLogLevel()
Set the logging to print additional logs to Android LogCat or Xcode logs. Call this before initializing OneSignal. See Getting a Debug Log for more details.
setAlertLevel()
Sets the logging level to show as alert dialogs in your app. Make sure to remove this before submitting to the app store.
When users open your app, OneSignal automatically creates a OneSignal ID (user-level) and a Subscription ID (device-level). You can associate multiple subscriptions (e.g., devices, emails, phone numbers) with a single user by calling login()
with your unique user identifier.
login(external_id)
Sets the user context to the provided external_id
. Ensures that all Subscriptions and properties associated with this external_id
are unified under a single onesignal_id
. See Users for more details.
Key behaviors:
external_id
already exists, the SDK switches to that user. Anonymous data collected before login is not merged and will be discarded.external_id
does not exist, the local state will be saved under the current onesignal_id
. Any data collected while the user was anonymous will be kept.login
every time the app identifies a user. logout()
Unlinks the current user from the subscription.
external_id
from the current push subscription.login
method.getOnesignalId()
Retrieve the current OneSignal ID. May be null
if called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
getExternalId()
Retrieve the current External ID. May be null
if not set or called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
addObserver()
user stateListen for changes in the user context (e.g., login, logout, ID assignment).
addAlias()
, addAliases()
, removeAlias()
, removeAliases()
Aliases are alternative identifiers (like usernames or CRM IDs).
external_id
with login()
before adding aliases. Aliases added to subscriptions without external_id
will not sync across multiple subscriptions.setLanguage()
Overrides the auto-detected language of the user. Use ISO 639-1 language code.
Tags are custom key : value
pairs of string data you set on users based on events or user properties. See Data Tags for more details.
addTag()
, addTags()
Set a single or multiple tags on the current user.
removeTag()
, removeTags()
Delete a single or multiple tags from the current user.
getTags()
Returns the local copy of the user’s tags. Tags are updated from the server during login()
or new app sessions.
setConsentRequired()
Enforces user consent before data collection begins. Must be called before initializing the SDK.
setConsentGiven()
Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.
setConsentRequired()
is true
, our SDK will not be fully enabled until setConsentGiven
is called with true
.setConsentGiven
is set to true
and a Subscription is created, then later it is set to false
, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until setConsentGiven
is set to true
again.Tracking location points requires 3 steps:
You may get the following errors:
LocationManager.startGetLocation: not possible, no location dependency found
Check your App’s dependencies. A common solutions is in you app/build.gradle
add: implementation 'com.google.android.gms:play-services-location:21.0.1'
Location.setShared()
method.Location.requestPermission
method or use in-app messages.setShared()
locationUse this method to allow our SDK to start tracking the Subscription’s latitude and longitude. Make sure you set the proper location permissions in your app first.
requestPermission()
locationUse this method to display the system-level location permission prompt to your users or instead use in-app messages. Make sure you set the proper location permissions in your app and enabled your app to share location with OneSignal.
See Subscriptions for more details.
User.pushSubscription.id
Returns the current push subscription ID. May return null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
User.pushSubscription.token
Returns the current push subscription token. May return null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
addObserver()
push subscription changesUse this method to respond to push subscription changes like:
optedIn
value changes (e.g. called optIn()
or optOut()
)When this happens, the SDK triggers the onPushSubscriptionChange
event. Your listener receives a state object with the previous
and current
values so you can detect exactly what changed.
To stop listening for updates, call the associated removeObserver()
or removeEventListener()
method.
optOut()
, optIn()
, optedIn
Control the subscription status (subscribed
or unsubscribed
) of the current push Subscription. Use these methods to control the push subscription status within your app. Common use cases: 1) Prevent push from being sent to users that log out. 2) Implement a notification preference center within your app.
optOut()
: Sets the current push subscription status to unsubscribed (even if the user has a valid push token).optIn()
: Does one of three actions:
subscribed
.Fallback to settings prompt
optedIn
: Returns true
if the current push subscription status is subscribed, otherwise false
. If the push token is valid but optOut()
was called, this will return false
.addEmail()
, removeEmail()
Adds or removes an email Subscription (email address) to/from the current user. Call addEmail
after login()
to set the correct user context. Compatible with Identity Verification.
addSms()
, removeSms()
Adds or removes an SMS Subscription (phone number) to/from the current user. Requires E.164 format. Call addSms
after login()
to set the correct user context. Compatible with Identity Verification.
requestPermission(fallbackToSettings)
pushShows the native system prompt asking the user for push notification permission. Optionally enable a fallback prompt that links to the settings app.
fallbackToSettings
: If true
, the fallback prompt will be displayed if the user denied push permissions more than the operating system’s limit (once iOS, twice Android).Fallback-to-settings prompt when permission is blocked
See Prompt for Push Permissions for more information.
addPermissionObserver()
pushUse this method to track push permission changes like:
When this happens, the SDK triggers the onOSPermissionChanged
event. Your listener receives a state object with the from
and to
values so you can detect exactly what changed.
To stop listening for updates, call the associated removePermissionObserver()
method.
getPermission()
, getCanRequestPermission()
getPermission()
returns the current push permission status at the app-level. It does not consider the OneSignal-level subscription status if you changed it via optOut()
or the enabled
parameter in the Users and Subscriptions APIs. Instead of using getPermission()
, we recommend using the Push Permission Observer to track changes in the device’s notification permission status while the app is running or the Push Subscription Observer to track changes in the push subscription status.
getCanRequestPermission()
returns whether attempting to request permission will result in a prompt being displayed to the user. If false
, the user has already denied permission and can either be shown the fallback prompt or no prompt at all. See Prompt for push permissions for more information.
permissionNative
iOSReturns an enum for the native permission of the iOS device. It will be one of:
0
= NotDetermined1
= Denied2
= Authorized3
= Provisional (only available in iOS 12+)4
= Ephemeral (only available in iOS 14+)addClickListener()
pushSet a callback that runs when a user clicks a push notification that opens the app.
The app’s activity or scene is already launched by the time this event fires. Use this handler to perform any custom logic — do not relaunch or duplicate app navigation manually.
Use removeClickListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
addForegroundLifecycleListener()
pushAllows you to intercept and control how notifications behave when the app is in the foreground.
By default, OneSignal automatically displays the notification. You can override this behavior using event.preventDefault()
to:
Call event.notification.display()
to manually show it later.
Use removeForegroundLifecycleListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
clearAllNotifications()
Removes all OneSignal notifications from the Notification Shade. Use instead of Android’s android.app.NotificationManager.cancel
. Otherwise, the notifications will be restored when your app is restarted.
removeNotification()
AndroidCancel a single notification based on its Android notification ID.
Use instead of Android’s android.app.NotificationManager.cancel
. Otherwise, the notification will be restored when your app is restarted.
removeGroupedNotifications()
AndroidCancel a group of OneSignal notifications with the provided group key. Grouping notifications is a OneSignal concept. There is no android.app.NotificationManager
equivalent.
In-app messages do not require any code; however, the SDK enables you to customize when messages are presented and handle lifecycle events.
addTrigger()
, addTriggers()
Decide when to display an In-App Message based on a single or multiple triggers. See Triggers for more information.
Triggers are not persisted to the backend. They only exist on the local device and apply to the current user.
removeTrigger()
, removeTriggers()
, clearTriggers()
Remove a single, multiple, or all triggers with the provided key from the current user.
paused
Prevent In-app messages from being displayed to the user. When set to true
, no in-app messages will be presented. When set to false
, any messages the user qualifies for will be presented to them at the appropriate time.
addLifecycleListener()
Respond to or track In-App Messages being displayed and dismissed.
addClickListener()
in-appRespond to in-app message click events. The event contains the following click action metadata:
actionId
: A custom identifier you set on the element.urlTarget
: An enum specifying how the launch URL for the message will be presented.url
: The launch URL for the action, if any.closingMessage
: A boolean value indicating if the action resulted in the message being closed.Applications should allow users to opt-in to Live Activities. For example, your app gives the user the option to start the Live Activity within your US using a button or presenting an IAM. You may start and update a Live Activity via any method without an explicit prompt, unlike Notification Permission or Location Permission. Live Activities appear with the iOS Provisional Authorization UI. Live Activities must be started when your application is in the foreground. We recommend reading Apple’s developer guidelines to learn more about Live Activities.
setup()
Allows OneSignal to manage the lifecycle of a LiveActivity on behalf of the application. This includes listening for both pushToStart token updates and pushToUpdate token updates.
setupDefault()
Allows cross platform SDK’s to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes. See Cross-platform setup for further details.
enter()
Entering a Live Activity associates an activityId
with a Live Activity Temporary Push Token on our server. Specify this identifier when using the Update Live Activities REST API to update one or multiple Live Activities simultaneously.
exit()
Exiting a Live activity deletes the association between an Activity Identifier with the Live Activity push token on our server.
setPushToStartToken()
Optional “low-level” approach to push to start live activities. Offers fine-grained control over the LiveActivity start and update tokens without altering the ActivityAttribute
structure. Additional details available here
removePushToStartToken()
Called per-activity-type whenever that activity type should no longer be registered against the current subscription
Track actions taken by users and attribute them to messages. See Outcomes for more details.
addOutcome()
Add an outcome with the provided name, captured against the current session.
addUniqueOutcome()
Add a unique outcome with the provided name, captured against the current session.
addOutcomeWithValue()
Add an outcome with the provided name and value captured against the current session.
Comprehensive API reference for the OneSignal Mobile SDK, including initialization, user identity, subscriptions, tags, permissions, in-app messages, live activities, and more. Supports Android, iOS, Unity, React Native, Flutter, and Cordova/Ionic platforms.
These methods are a reference for integrating the OneSignal SDK into your app. For full platform-specific setup instructions, see Mobile SDK setup.
initialize()
Initializes the OneSignal SDK. This should be called during application startup. The ONESIGNAL_APP_ID
can be found in Keys & IDs.
If you want to delay initialization of the OneSignal SDK, we recommend using our Privacy methods.
setLogLevel()
Set the logging to print additional logs to Android LogCat or Xcode logs. Call this before initializing OneSignal. See Getting a Debug Log for more details.
setAlertLevel()
Sets the logging level to show as alert dialogs in your app. Make sure to remove this before submitting to the app store.
When users open your app, OneSignal automatically creates a OneSignal ID (user-level) and a Subscription ID (device-level). You can associate multiple subscriptions (e.g., devices, emails, phone numbers) with a single user by calling login()
with your unique user identifier.
login(external_id)
Sets the user context to the provided external_id
. Ensures that all Subscriptions and properties associated with this external_id
are unified under a single onesignal_id
. See Users for more details.
Key behaviors:
external_id
already exists, the SDK switches to that user. Anonymous data collected before login is not merged and will be discarded.external_id
does not exist, the local state will be saved under the current onesignal_id
. Any data collected while the user was anonymous will be kept.login
every time the app identifies a user. logout()
Unlinks the current user from the subscription.
external_id
from the current push subscription.login
method.getOnesignalId()
Retrieve the current OneSignal ID. May be null
if called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
getExternalId()
Retrieve the current External ID. May be null
if not set or called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
addObserver()
user stateListen for changes in the user context (e.g., login, logout, ID assignment).
addAlias()
, addAliases()
, removeAlias()
, removeAliases()
Aliases are alternative identifiers (like usernames or CRM IDs).
external_id
with login()
before adding aliases. Aliases added to subscriptions without external_id
will not sync across multiple subscriptions.setLanguage()
Overrides the auto-detected language of the user. Use ISO 639-1 language code.
Tags are custom key : value
pairs of string data you set on users based on events or user properties. See Data Tags for more details.
addTag()
, addTags()
Set a single or multiple tags on the current user.
removeTag()
, removeTags()
Delete a single or multiple tags from the current user.
getTags()
Returns the local copy of the user’s tags. Tags are updated from the server during login()
or new app sessions.
setConsentRequired()
Enforces user consent before data collection begins. Must be called before initializing the SDK.
setConsentGiven()
Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.
setConsentRequired()
is true
, our SDK will not be fully enabled until setConsentGiven
is called with true
.setConsentGiven
is set to true
and a Subscription is created, then later it is set to false
, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until setConsentGiven
is set to true
again.Tracking location points requires 3 steps:
You may get the following errors:
LocationManager.startGetLocation: not possible, no location dependency found
Check your App’s dependencies. A common solutions is in you app/build.gradle
add: implementation 'com.google.android.gms:play-services-location:21.0.1'
Location.setShared()
method.Location.requestPermission
method or use in-app messages.setShared()
locationUse this method to allow our SDK to start tracking the Subscription’s latitude and longitude. Make sure you set the proper location permissions in your app first.
requestPermission()
locationUse this method to display the system-level location permission prompt to your users or instead use in-app messages. Make sure you set the proper location permissions in your app and enabled your app to share location with OneSignal.
See Subscriptions for more details.
User.pushSubscription.id
Returns the current push subscription ID. May return null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
User.pushSubscription.token
Returns the current push subscription token. May return null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
addObserver()
push subscription changesUse this method to respond to push subscription changes like:
optedIn
value changes (e.g. called optIn()
or optOut()
)When this happens, the SDK triggers the onPushSubscriptionChange
event. Your listener receives a state object with the previous
and current
values so you can detect exactly what changed.
To stop listening for updates, call the associated removeObserver()
or removeEventListener()
method.
optOut()
, optIn()
, optedIn
Control the subscription status (subscribed
or unsubscribed
) of the current push Subscription. Use these methods to control the push subscription status within your app. Common use cases: 1) Prevent push from being sent to users that log out. 2) Implement a notification preference center within your app.
optOut()
: Sets the current push subscription status to unsubscribed (even if the user has a valid push token).optIn()
: Does one of three actions:
subscribed
.Fallback to settings prompt
optedIn
: Returns true
if the current push subscription status is subscribed, otherwise false
. If the push token is valid but optOut()
was called, this will return false
.addEmail()
, removeEmail()
Adds or removes an email Subscription (email address) to/from the current user. Call addEmail
after login()
to set the correct user context. Compatible with Identity Verification.
addSms()
, removeSms()
Adds or removes an SMS Subscription (phone number) to/from the current user. Requires E.164 format. Call addSms
after login()
to set the correct user context. Compatible with Identity Verification.
requestPermission(fallbackToSettings)
pushShows the native system prompt asking the user for push notification permission. Optionally enable a fallback prompt that links to the settings app.
fallbackToSettings
: If true
, the fallback prompt will be displayed if the user denied push permissions more than the operating system’s limit (once iOS, twice Android).Fallback-to-settings prompt when permission is blocked
See Prompt for Push Permissions for more information.
addPermissionObserver()
pushUse this method to track push permission changes like:
When this happens, the SDK triggers the onOSPermissionChanged
event. Your listener receives a state object with the from
and to
values so you can detect exactly what changed.
To stop listening for updates, call the associated removePermissionObserver()
method.
getPermission()
, getCanRequestPermission()
getPermission()
returns the current push permission status at the app-level. It does not consider the OneSignal-level subscription status if you changed it via optOut()
or the enabled
parameter in the Users and Subscriptions APIs. Instead of using getPermission()
, we recommend using the Push Permission Observer to track changes in the device’s notification permission status while the app is running or the Push Subscription Observer to track changes in the push subscription status.
getCanRequestPermission()
returns whether attempting to request permission will result in a prompt being displayed to the user. If false
, the user has already denied permission and can either be shown the fallback prompt or no prompt at all. See Prompt for push permissions for more information.
permissionNative
iOSReturns an enum for the native permission of the iOS device. It will be one of:
0
= NotDetermined1
= Denied2
= Authorized3
= Provisional (only available in iOS 12+)4
= Ephemeral (only available in iOS 14+)addClickListener()
pushSet a callback that runs when a user clicks a push notification that opens the app.
The app’s activity or scene is already launched by the time this event fires. Use this handler to perform any custom logic — do not relaunch or duplicate app navigation manually.
Use removeClickListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
addForegroundLifecycleListener()
pushAllows you to intercept and control how notifications behave when the app is in the foreground.
By default, OneSignal automatically displays the notification. You can override this behavior using event.preventDefault()
to:
Call event.notification.display()
to manually show it later.
Use removeForegroundLifecycleListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
clearAllNotifications()
Removes all OneSignal notifications from the Notification Shade. Use instead of Android’s android.app.NotificationManager.cancel
. Otherwise, the notifications will be restored when your app is restarted.
removeNotification()
AndroidCancel a single notification based on its Android notification ID.
Use instead of Android’s android.app.NotificationManager.cancel
. Otherwise, the notification will be restored when your app is restarted.
removeGroupedNotifications()
AndroidCancel a group of OneSignal notifications with the provided group key. Grouping notifications is a OneSignal concept. There is no android.app.NotificationManager
equivalent.
In-app messages do not require any code; however, the SDK enables you to customize when messages are presented and handle lifecycle events.
addTrigger()
, addTriggers()
Decide when to display an In-App Message based on a single or multiple triggers. See Triggers for more information.
Triggers are not persisted to the backend. They only exist on the local device and apply to the current user.
removeTrigger()
, removeTriggers()
, clearTriggers()
Remove a single, multiple, or all triggers with the provided key from the current user.
paused
Prevent In-app messages from being displayed to the user. When set to true
, no in-app messages will be presented. When set to false
, any messages the user qualifies for will be presented to them at the appropriate time.
addLifecycleListener()
Respond to or track In-App Messages being displayed and dismissed.
addClickListener()
in-appRespond to in-app message click events. The event contains the following click action metadata:
actionId
: A custom identifier you set on the element.urlTarget
: An enum specifying how the launch URL for the message will be presented.url
: The launch URL for the action, if any.closingMessage
: A boolean value indicating if the action resulted in the message being closed.Applications should allow users to opt-in to Live Activities. For example, your app gives the user the option to start the Live Activity within your US using a button or presenting an IAM. You may start and update a Live Activity via any method without an explicit prompt, unlike Notification Permission or Location Permission. Live Activities appear with the iOS Provisional Authorization UI. Live Activities must be started when your application is in the foreground. We recommend reading Apple’s developer guidelines to learn more about Live Activities.
setup()
Allows OneSignal to manage the lifecycle of a LiveActivity on behalf of the application. This includes listening for both pushToStart token updates and pushToUpdate token updates.
setupDefault()
Allows cross platform SDK’s to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes. See Cross-platform setup for further details.
enter()
Entering a Live Activity associates an activityId
with a Live Activity Temporary Push Token on our server. Specify this identifier when using the Update Live Activities REST API to update one or multiple Live Activities simultaneously.
exit()
Exiting a Live activity deletes the association between an Activity Identifier with the Live Activity push token on our server.
setPushToStartToken()
Optional “low-level” approach to push to start live activities. Offers fine-grained control over the LiveActivity start and update tokens without altering the ActivityAttribute
structure. Additional details available here
removePushToStartToken()
Called per-activity-type whenever that activity type should no longer be registered against the current subscription
Track actions taken by users and attribute them to messages. See Outcomes for more details.
addOutcome()
Add an outcome with the provided name, captured against the current session.
addUniqueOutcome()
Add a unique outcome with the provided name, captured against the current session.
addOutcomeWithValue()
Add an outcome with the provided name and value captured against the current session.