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.

📘

Just starting with React Native?

Check out our React Native SDK Setup guide.

Parameter

Data Type

Description

Debugging

setLogLevel

Method

Enable logging to help debug OneSignal implementation.

Initialization

init

Method

Starts initialization of OneSignal, call this from App.js or index.js. See React Native SDK Setup for details and code examples.

inFocusDisplaying

Method

Setting to control how OneSignal notifications will be shown when one is received while your app is in focus.

iOS Settings

Keys

iOS - Automatically prompt users to enable notifications and open all URLs in In-App Safari window.

Events & Listeners

Method

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.

Handling Notifications

Method

Handle tracking of notification received and clicked events.

Privacy

setRequiresUserPrivacyConsent

Delays initialization of the SDK until the user provides privacy consent

consentGranted

Tells the SDK that the user has provided privacy consent (if required)

iOS Prompting

promptForPushNotificationsWithUserResponse

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

getPermissionSubscriptionState

Get the current notification and permission state. Returns a OSPermissionSubscriptionState type.

addPermissionObserver

Observer method for Current Device Record's Permission status changes.

addSubscriptionObserver

Method

Observer method for Current Device Record's Subscription status changes.

setSubscription

Method

Disable OneSignal from sending notifications to current device.

External IDs

setExternalUserId

Method

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

Method

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

Tagging

getTags

Method

View Tags from current device record.

sendTag

Method

Add a single Data Tag to current device record.

sendTags

Method

Add multiple Data Tags to current device record.

deleteTag

Method

Delete a Tag from current device record.

deleteTags

Method

Delete multiple Tags from current device record.

Location Data

setLocationShared

Method

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

promptLocation

Method

Prompt Users for Location Not Recommended

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

Sending Notifications

postNotification

Method

Send or schedule a notification to a OneSignal Player ID.

clearNotification

Method

Android Only Delete all app notifications

In-App Messaging

addTrigger

Method

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

addTriggers

Method

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

removeTriggerForKey

Method

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

getTriggerValueForKey

Method

Gets a trigger value for a provided trigger key.

pauseInAppMessages

Method

Allows you to temporarily pause all In App Messages.

setInAppMessageClickHandler

Method

Sets an In App Message opened block

Email

setEmail

Method

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

Method

Log user out to dissociate email from device

addEmailSubscriptionObserver

Method

Observer for subscription changes to email

Initialization

iOS Initialization Parameters

These settings are passed to the iOS SDK at initialization, such as:

OneSignal.init(appId, {kOSSettingsKeyAutoPrompt : true});

At the present time, none of these settings are available in the Android SDK.

Settings Key

Data Type

Description

kOSSettingsKeyAutoPrompt

Boolean

Automatically Prompt Users to Enable Notifications. See React Native & Expo SDK Setup for code examples.

true (Default) - automatically prompts for notifications permissions.

false - disables auto prompt.

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

kOSSettingsKeyInAppLaunchURL

Boolean

Open URLs in In-App Safari Window or Safari app. See React Native & Expo SDK Setup for code examples.

true (Default) - Open all URLs with a in-app WebView window.

false - Launches Safari with the URL OR other app (if deep linked or custom URL scheme passed).

kOSSSettingsKeyPromptBeforeOpeningPushURL

Boolean

Determines if the app will pop up an alert view to ask the user if they want to open a URL. If this setting is false, the application will immediately open the web browser when the user taps a notification with a launch URL

Events & Listeners

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.

addEventListener - Use this method to add a callback to an event.

removeEventListener - Use this method to remove a callback from an event.

OneSignal.addEventListener('received', this.onReceived); // where onReceived is a callback
OneSignal.removeEventListener('received', this.onReceived);

Events

Event String

Description

"received"

Fires when a notification is received in the foreground.

"opened"

Fires when a notification is opened (tapped)

"ids"

Fires when ids are available

"inAppMessageClicked"

Fires when In-App message action

Handling Notifications

Opened and Received Events

When a notification is tapped and opens the app, the onOpened event will fire.

When a notification is received in the foreground the onReceived event will fire.

The callback functions defined in the listeners will pass an OSNotificationOpenResult or an OSNotification object encapsulating the event data.

componentWillMount() {
    OneSignal.addEventListener('received', this.onReceived);
    OneSignal.addEventListener('opened', this.onOpened);
}

onReceived(notification) {
    console.log("Notification received: ", notification);
}

onOpened(openResult) {
    console.log('Message: ', openResult.notification.payload.body);
    console.log('Data: ', openResult.notification.payload.additionalData);
    console.log('isActive: ', openResult.notification.isAppInFocus);
}

OSNotification object received example:

{
    shown: true, // BOOLEAN: If the notification was displayed to the user or not
    payload: {notificationID : "", contentAvailable : false, badge : 1, sound : "default", title : "Hello!", body : "World", launchURL : "", }, // OBJECT; the push data
    displayType: 1 //The display method of a received notification
}

Player & Device Info

Getting Player ID and Push Token

With the latest versions of the OneSignal React Native SDK, you can use the permission and subscription observer methods along with getPermissionSubscriptionState to get more details. See our [User Status SDK Methods(https://documentation.onesignal.com/docs/sdk-reference#user-status) for more details.

The React Native SDK contains the method onIds which returns the pushToken and player_id
Listen for ids event and define a callback to handle the returned object.

componentWillMount() {
    OneSignal.init("YOUR_ONESIGNAL_APPID");

    OneSignal.addEventListener('ids', this.onIds);
}

componentWillUnmount() {
    OneSignal.removeEventListener('ids', this.onIds);
}

onIds(device) {
    console.log('Device info: ', device);
}

Behavior

Enable Vibration

We exposed the enableVibrate API of OneSignal (Android only).

You can call this from your UI from a button press for example to give your user's options for your notifications. By default OneSignal always vibrates the device when a notification is displayed unless the device is in a total silent mode. Passing false means that the device will only vibrate lightly when the device is in it's vibrate only mode.

// Setting enableVibrate
OneSignal.enableVibrate(true);

Enable Sound

We exposed the enableSound API of OneSignal (Android only).

You can call this from your UI from a button press for example to give your user's options for your notifications. By default OneSignal plays the system's default notification sound when the device's notification system volume is turned on. Passing false means that the device will only vibrate unless the device is set to a total silent mode.

// Setting enableSound
OneSignal.enableSound(true);

Clear Notifications (Android Only)

Removes all OneSignal notifications from the Notification Shade.

// Calling clearOneSignalNotifications
OneSignal.clearOneSignalNotifications();

Cancel Notifications (Android Only)

Cancels a single OneSignal notification based on its Android notification integer id. You can get the notification Id when invoking OneSignal.onNotificationOpened while receiving a notification.

// Calling cancelNotification
OneSignal.cancelNotification(id);

Request Push Notification Permissions (iOS Only)

// Setting requestPermissions
permissions = {
    alert: true,
    badge: true,
    sound: true
};
OneSignal.requestPermissions(permissions);

Updated 13 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.