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.
initialize()
ONESIGNAL_APP_ID
can be found in Keys & IDs.
setLogLevel()
setAlertLevel()
login()
with your unique user identifier.
login(external_id)
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()
external_id
from the current push subscription.login
method.getOnesignalId()
null
if called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
getExternalId()
null
if not set or called before user state is initialized. Instead, use User State addObserver()
to listen for user state changes.
addObserver()
user stateaddAlias()
, addAliases()
, removeAlias()
, removeAliases()
external_id
with login()
before adding aliases. Aliases added to subscriptions without external_id
will not sync across multiple subscriptions.setLanguage()
key : value
pairs of string data you set on users based on events or user properties. See Data Tags for more details.
addTag()
, addTags()
removeTag()
, removeTags()
getTags()
login()
or new app sessions.
setConsentRequired()
setConsentGiven()
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.LocationManager.startGetLocation: not possible, no location dependency foundCheck 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()
locationrequestPermission()
locationUser.pushSubscription.id
null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
User.pushSubscription.token
null
if called too early. Its recommended to get this data within the subscription observer to react to changes.
addObserver()
push subscription changesoptedIn
value changes (e.g. called optIn()
or optOut()
)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
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()
addEmail
after login()
to set the correct user context. Compatible with Identity Verification.
addSms()
, removeSms()
addSms
after login()
to set the correct user context. Compatible with Identity Verification.
requestPermission(fallbackToSettings)
pushfallbackToSettings
: 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
addPermissionObserver()
pushonOSPermissionChanged
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
iOS0
= NotDetermined1
= Denied2
= Authorized3
= Provisional (only available in iOS 12+)4
= Ephemeral (only available in iOS 14+)addClickListener()
pushremoveClickListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
addForegroundLifecycleListener()
pushevent.preventDefault()
to:
event.notification.display()
to manually show it later.
removeForegroundLifecycleListener()
or removeEventListener()
to stop listening when the handler is no longer needed.
clearAllNotifications()
android.app.NotificationManager.cancel
. Otherwise, the notifications will be restored when your app is restarted.
removeNotification()
Androidandroid.app.NotificationManager.cancel
. Otherwise, the notification will be restored when your app is restarted.
removeGroupedNotifications()
Androidandroid.app.NotificationManager
equivalent.
addTrigger()
, addTriggers()
removeTrigger()
, removeTriggers()
, clearTriggers()
paused
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()
addClickListener()
in-appactionId
: 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.setup()
setupDefault()
enter()
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()
setPushToStartToken()
ActivityAttribute
structure. Additional details available here
removePushToStartToken()
addOutcome()
addUniqueOutcome()
addOutcomeWithValue()