OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

React Native SDK

OneSignal React Native SDK. Works with iOS and Android.

🚧

This reference covers version 4.0.0+ of the React Native SDK

For the old reference, click here.

Coming from version 3? See full changes in version 4 in our Migration Guide.

πŸ“˜

Just starting with React Native?

Check out our React Native SDK Setup guide.

Parameter

Data Type

Description

Debugging

setLogLevel

Function

Enable logging to help debug OneSignal implementation.

Initialization

setAppId()

Function

  • Required: Set the OneSignal app id.

Events, Handlers, & Observers

The OneSignal SDK emits various "events" such as the receipt of a notification or a click event. You can use the following methods to attach and remove callbacks to these events.

addPermissionObserver()

Function

Add a callback that fires when the native push permission changes.

addSubscriptionObserver()

Function

Add a callback that fires when the OneSignal subscription state changes.

addEmailSubscriptionObserver()

Function

Add a callback that fires when the OneSignal email subscription changes.

setNotificationWillShowInForegroundHandler()

Function

Set the callback to run just before displaying a notification while the app is in focus.

setInAppMessageClickHandler()

Function

Set the callback to run on in-app message click.

setNotificationOpenedHandler()

Function

Set the callback to run on notification open.

Privacy

setRequiresUserPrivacyConsent

Function

Delays initialization of the SDK until the user provides privacy consent

userProvidedPrivacyConsent

Function

Whether or not the user has provided privacy consent (if required)

provideUserConsent

Function

If your application is set to require the user's privacy consent, you can provide this consent using this method. Until you call provideUserConsent(true), the SDK will not fully initialize, and will not send any data to OneSignal.

iOS Prompting

promptForPushNotificationsWithUserResponse

Function

Prompt the user for notification permissions. Callback fires as soon as the user accepts or declines notifications.

Must set kOSSettingsKeyAutoPrompt to false when calling initWithLaunchOptions.

Recommended: Set to false and follow iOS Push Opt-In Prompt.

User Status

More Details

getDeviceState()

Function

Gets information about the device.

disablePush()

Function

Disable the push notification subscription to OneSignal.

External IDs

setExternalUserId

Function

Allows you to use your own system's user ID's to send push notifications to your users. To tie a user to a given user ID, you can use this method.

removeExternalUserId

Function

Removes whatever was set as the current user's external user ID.

Tagging

getTags

Function

View Tags from current device record.

sendTag

Function

Add a single Data Tag to current device record.

sendTags

Function

Add multiple Data Tags to current device record.

deleteTag

Function

Delete a Tag from current device record.

deleteTags

Function

Delete multiple Tags from current device record.

Location Data

setLocationShared

Function

Disable or Enable SDK location collection. See Handling Personal Data.

promptLocation

Function

Prompt Users for Location Not Recommended

Recommended: Use In-App Message Location Opt-In Prompt.

Sending Notifications

postNotification

Function

Send or schedule a notification to a OneSignal Player ID.

clearNotification

Function

Android Only Delete all app notifications

In-App Messaging

addTrigger

Function

Add a trigger, may show an In-App Message if its triggers conditions were met.

addTriggers

Function

Add a map of triggers, may show an In-App Message if its triggers conditions were met.

removeTriggerForKey

Function

Removes a list of triggers based on a collection of keys, may show an In-App Message if its triggers conditions were met.

getTriggerValueForKey

Function

Gets a trigger value for a provided trigger key.

pauseInAppMessages

Function

Allows you to temporarily pause all In App Messages.

setInAppMessageClickHandler

Function

Sets an In App Message opened block

Outcomes

sendOutcome

Function

Increases the outcome count by 1 and will be counted each time sent.

sendUniqueOutcome

Function

Increases count by 1 only once. This can only be attributed to a single notification. If the method is called outside of an attribution window, it will be unattributed until a new session occurs.

sendOutcomeWithValue

Function

Increases the count by 1 and the sum by the value. Will be counted each time sent.

Email

setEmail

Function

Set user's email. Creates a new user record for the email address. Use sendTag if you want to update a push user record with the email.

logoutEmail

Function

Log user out to dissociate email from device

Other

clearOneSignalNotifications

Function

Removes all OneSignal notifications from the Notification Shade.

removeNotification

Function

This function is used to remove a notification from the Android shade by supplying the Android notification identifier.

clearHandlers

Function

Clears all handlers and observers.

Initialization

setAppId Function

To initialize, simply set the OneSignal application ID.

You can call setAppId at any point in your app's flow. This allows full initialization to be delayed until say, a user logs in.

OneSignal.setAppId(appId);

Foreground Notification Control

You can specifically read notification data that will display while the app is in focus as well as change the display type dynamically. This allows developers to have even greater control over the notification experience.

Replaces inFocusDisplaying() functionality.

setNotificationWillShowInForegroundHandler Function

Runs before displaying a notification while the app is in focus. Use this handler to decide if the notification should show or not.

Note: this runs after the Notification Service Extension which can be used to modify the notification before showing it (native code required).

The callback argument is a notification received event object.

OneSignal.setNotificationWillShowInForegroundHandler(notifReceivedEvent => {
    console.log("OneSignal: notification will show in foreground:", notifReceivedEvent);
    let notif = notifReceivedEvent.getNotification();
    notifReceivedEvent.complete(notif);
});

The callback argument object has two functions:

Field

Description

getNotification()

Retrieves the notification object.

This returned object is of class (OSNotification).

complete()

Show Notification:
Pass the notification to this function in order to display it while the app is in the foreground.

Silence Notification:
If you would like to silence the notification, call complete() with no argument.

🚧

iOS - Do not call the userNotificationCenter completionHandler from the App Delegate

For the above to work as intended, make sure to not call your own userNotificationCenter completionHandler from the App Delegate. Other libraries may require this. However, this will lead to a conflict with the OneSignal SDK.

Handlers

setInAppMessageClickHandler Function

Set the callback to run on an In-App Message click.

OneSignal.setInAppMessageClickHandler(event => {
    console.log("OneSignal IAM clicked:", event);
});

Click event parameters:

Parameter

Description

click_name

An optional click name entered defined by the app developer when creating the IAM.

click_url

An optional URL that opens when the action takes place.

closes_message

Whether tapping on the element closed the In-App Message.

first_click

Whether this was the first action taken on the in app message.

outcomes

Outcome for action.

Mainly useful for debugging

prompts

Permission prompts.

Mainly useful for debugging

tags

Tags for action.

Mainly useful for debugging

url_target

Determines where the URL is opened, ie.

Mainly useful for debugging

setNotificationOpenedHandler Function

Set the callback to run on notification open/click.

OneSignal.setNotificationOpenedHandler(openedEvent => {
    console.log("OneSignal: notification opened:", openedEvent);
  const { action, notification } = openedEvent;
});

Opened event parameters:

Parameter

Description

action

The action the user took on the notification.

Parameter:
type:

  1. notification was clicked
  2. button was clicked

notification

The notification the user received.

Of class OSNotification

🚧

Deep linking in iOS from an app closed state

As you can see in our deep linking reference, you can use Launch URLs to deep-link to pages within your application. However, there is an existing issue where the native click event is fired before the React lifecycle starts and has enough time to load the app, leading to that event getting missed.

Workarounds:

  1. Deep-link using additional data and use a router to take users to the correct page / screen.
  2. Modify the application:didFinishLaunchingWithOptions in your AppDelegate.m file to use the following:
NSMutableDictionary *newLaunchOptions = [NSMutableDictionary dictionaryWithDictionary:launchOptions];
    if (launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey]) {
        NSDictionary *remoteNotif = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];
        if (remoteNotif[@"custom"] && remoteNotif[@"custom"][@"u"]) {
            NSString *initialURL = remoteNotif[@"custom"][@"u"];
            if (!launchOptions[UIApplicationLaunchOptionsURLKey]) {
                newLaunchOptions[UIApplicationLaunchOptionsURLKey] = [NSURL URLWithString:initialURL];
            }
        }
    }

RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:newLaunchOptions];

You should already have the line RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:launchOptions];. This line should be replaced by the new code's last line.

Observers

Each callback you pass to an observer adder function will receive a state change object when fired that contains two parameters: to and from. The parameters on those objects are the same between the two. This format allows for the detection of the previous state and the new state.

Example: a change in the subscription state of the device might see the isSubscribed parameter change from false to true. You can detect the change by the event.from.isSubscribed and event.to.isSubscribed objects.

Important: as designated by the "add" prefix to these functions, it is possible to add multiple callbacks to the same event. The callbacks will then fire independently when the event occurs. (Related: see clearHandlers function).

addPermissionObserver Function

Add a callback that fires when the native push permission changes.

Change event parameters:

Parameter

Description

areNotificationsEnabled (Android)

Whether the device-level permission is granted or denied (boolean).

hasPrompted (iOS)

Did the user answer the notification permission prompt.

provisional (iOS)

Is provisional push authorization enabled.

status (iOS)

0 - "NotDetermined"
1 - "Denied"
2 - "Authorized"
3 - "Provisional"
4 - "Ephemeral"

addSubscriptionObserver Function

Add a callback that fires when the OneSignal subscription state changes.

Change event parameters:

Parameter

Description

userId

The OneSignal player identifier.

pushToken

The native push token identifier used by FCM / HMS / FireOS / APNs.

isPushDisabled

Is push disabled (disablePush was called).

isSubscribed (Android)

Whether the player is subscribed to OneSignal.

addEmailSubscriptionObserver Function

Add a callback that fires when the OneSignal email subscription changes.

Change event parameters:

Parameter

Description

emailAddress

The email address associated with this player record.

emailUserId

The UUID associated with the email record.

isSubscribed

Whether the associated email record is subscribed to OneSignal messaging.

Example

OneSignal.addPermissionObserver(event => {
    console.log("OneSignal: permission changed:", event);
});

OneSignal.addSubscriptionObserver(event => {
    console.log("OneSignal: subscription changed:", event);
});

OneSignal.addEmailSubscriptionObserver((event) => {
    console.log("OneSignal: email subscription changed: ", event);
});

Other Functions

getDeviceState Function

ASYNC
Returns an OSDeviceState object with device info.

🚧

Do not cache OSDeviceState object

This method returns a "snapshot" of the device state for when it was called. Make sure to call getDeviceState again to get the latest state.

const deviceState = await OneSignal.getDeviceState();

deviceState parameters:

Type

Description

isSubscribed

Get whether the device is subscribed to receive OneSignal push notifications.

isPushDisabled

Was push disabled with disablePush.

userId

Get the OneSignal user (player) id

pushToken

Get device's push token.
This can be one of the following depending on the device:

  • Google FCM token
  • Huawei HMS token
  • FireOS token

emailUserId

Get the OneSignal user email id.
Only available if OneSignal.setEmail() was called.

emailAddress

Get the user email address.
Only available if OneSignal.setEmail() was called.

isEmailSubscribed

Is there an associated email record that is subscribed to OneSignal messaging.

hasNotificationPermission

iOS Only

Whether notifications are enabled on the device at the app level.

notificationPermissionStatus

iOS Only

0 = NotDetermined
1 = Denied
2 = Authorized
3 = Provisional
4 = Ephemeral

disablePush Function

Use this function to opt users out of receiving all notifications through OneSignal.

OneSignal.disablePush(true);

clearHandlers Function

Clears all handlers and observers.

πŸ“˜

While this function clears both handlers AND observers, it is mainly useful for the observers since multiple observers can be added to a single event. React Native hot-reloading can lead to the buildup of these observers while in the dev environment which will result in multiple firings of the given callbacks. To avoid this, call in componentWillUnmount().


OSNotification

Name

Description

OSNotification

Contains all notification properties such as title, body, additionalData, etc...

OSNotification Object

In version 4, the OSNotification class is composed of all notification properties in a single object. This is the object passed into the notificationWillShowInForeground handler.

Parameter

Description

additionalData

Custom additional data that was sent with the notification. Set on the dashboard under Options > Additional Data or with the data field on the REST API.

notificationId

The OneSignal notification UUID.

body

The body text of the notification.

title

The title text of the notification.

launchUrl

The URL opened when opening the notification.

actionButtons

The list of action buttons on the notification.

sound

The sound resource played when the notification is shown.

rawPayload

The raw JSON payload string received from OneSignal.

largeIcon (Android)

The large icon set on the notification.

bigPicture (Android)

The big picture image set on the notification.

smallIcon (Android)

The small icon resource name set on the notification.

smallIconAccentColor (Android)

The accent color shown around small notification icon on Android 5+ devices. ARGB format.

ledColor (Android)

LED string. Devices that have a notification LED will blink in this color. ARGB format.

collapseId (Android)

The collapse id for the notification.

priority (Android)

The priority of the notification. Values range from -2 to 2 (see Android's NotificationCompat reference for more info.

fromProjectNumber (Android)

The Google project number the notification was sent under.

groupKey (Android)

Notifications with this same key will be grouped together as a single summary notification.

groupMessage (Android)

The summary text displayed in the summary notification.

lockScreenVisibility (Android)

Privacy setting for how the notification should be shown on the lockscreen of Android 5+ devices.

1 (Default) - Public (fully visible)
0 - Private (Contents are hidden)
-1 - Secret (not shown).

badge (iOS)

The badge number assigned to the application icon.

category (iOS)

Notification category key previously registered to display with.

threadId (iOS)

iOS 10+ only. Groups notifications into threads.

subtitle (iOS)

The message subtitle.

attachments (iOS)

iOS 10+ only. Attachments sent as part of the rich notification.

templateId (iOS)

Unique Template Identifier.

templateName (iOS)

Name of Template.

mutableContent (iOS)

True when the key mutable-content is set to 1 in the APNS payload.

See Apple's documentation for more details.

badgeIncrement (iOS)

The amount to increment the badge icon number.

contentAvailable (iOS)

True when the key content-available is set to 1 in the APNS payload. Used to wake your app when the payload is received.

See Apple's documentation for more details.


Privacy

userProvidedPrivacyConsent Function

Whether the user has provided privacy consent (if required).

Clear Notifications (Android Only)

clearOneSignalNotifications Function

Removes all OneSignal notifications from the Notification Shade.

// Calling clearOneSignalNotifications
OneSignal.clearOneSignalNotifications();

Remove Notifications (Android Only)

removeNotification Function

This function is used to remove a notification from the Android shade by supplying the Android notification identifier. The notification identifier can be found as part of the OSNotification object.

// Calling removeNotification
OneSignal.removeNotification(id);

Typescript Support

Versions 4.0+ of the React Native SDK include Typescript typings.


Troubleshooting

Troubleshooting the React Native SDK

Updated 29 days ago


React Native SDK


OneSignal React Native SDK. Works with iOS and Android.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.