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.

For Developers

Just starting with React Native?

API

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

Determines if the application automatically prompts the user for permission to send push notification the first time the application opens.

kOSSettingsKeyInAppLaunchURL

Boolean

Determines if the application opens push notification URL's in an in-app web browser view, or exits the app and opens the URL in Safari

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

kOSSettingsKeyInFocusDisplayOption

Integer

Determines how the app will display push notifications.

0 = None: When your app is open, OneSignal will not display a notification (it will be up to your app to provide a custom UI to display it)

1 = In App Alert: Notifications will display as a popup

2 = Notification: Notifications will display as normal notifications.

Handling Notifications

When any notification is opened or received the opened and received are activated and calling their callback functions defined in the listeners, passing an OSNotificationOpenResult or an OSNotification object encapsulating the event data.

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

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

componentWillUnmount() {
    OneSignal.removeEventListener('received', this.onReceived);
    OneSignal.removeEventListener('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);
    console.log('openResult: ', openResult);
}

Notification 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
    silentNotification: false // BOOLEAN : Wether the received notification was a silent one
}

Sending and Getting OneSignal Tags

We exposed the tags API of OneSignal to allow you to target users with notification later.

// Sending single tag
OneSignal.sendTag("key", "value");

// Sending multiple tags
OneSignal.sendTags({key: "value", key2: "value2"});

// Getting the tags from the server and use the received object
OneSignal.getTags((receivedTags) => {
    console.log(receivedTags);
});

// Delete a tag
OneSignal.deleteTag("key");

Using Email Features

OneSignal now allows you to send emails to your userbase. This email can be set using the OneSignal react-native SDK.

To set the email:

let emailAuthCode = ""; //Your email auth code should be securely generated by your backend server

OneSignal.setEmail("test@test.com", emailAuthCode, {(error) => {
    //handle error if it occurred
}});

If you don't want to implement email auth hashing on your backend (which is heavily recommended), you can still use the OneSignal email feature in an unauthenticated state like this:

OneSignal.setEmail("test@test.com", {(error) => {
    //handle error if it occurred
}});

If your application implements logout functionality, you can logout of the OneSignal email for this user using the logout function:

OneSignal.logoutEmail({(error) => {
    //handle error if it occurred
}});

Getting Player ID and Push Token

We exposed the idsAvailable API of OneSignal (both Android & iOS) as an event.
Listen for ids event and define a callback to handle the returned object.

Please note that calling OneSignal.configure() causes the ids event to fire.

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

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

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

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

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

Set In App Focus Behavior

We exposed the inFocusDisplaying API of OneSignal.

Both iOS and Android

  • 0 = None - Will not display a notification, instead only onNotificationReceived will fire where you can display your own in app messages.
  • 1 = InAppAlert - (Default) Will display an Android AlertDialog with the message contains.
  • 2 = Notification - Notification will display in the Notification Shade. Same as when the app is not in focus.
// Example, always display notification in shade.
OneSignal.inFocusDisplaying(2);

Change User Subscription Status

We exposed the setSubscription API of OneSignal (both Android & iOS).

You can call this method with false to opt users out of receiving all notifications through OneSignal. You can pass true later to opt users back into notifications

// Setting setSubscription
OneSignal.setSubscription(true);

Check Push Notification and User Subscription Status

We exposed the getPermissionSubscriptionState API of OneSignal (both Android & iOS).

Allows you to check whether notifications are enabled for the app, whether user is subscribed to notifications through OneSignal, and what the user's in-app subscription preference is. It also provides access to pushToken and userId

// Check push notification and OneSignal subscription statuses
OneSignal.getPermissionSubscriptionState((status) => {
    console.log(status);
});

Post Notification (Peer-to-Peer Notifications)

We exposed the postNotification API of OneSignal, currently supports one Player ID to send a notification to.
We call it internally P2P Notification, and therefore there is a special attribute to listen to while receiving the notification.

Allows you to send notifications from user to user or schedule ones in the future to be delivered to the current device.

The OneSignal documentation shows how to pass the parameters as here:

// Calling postNotification

let otherParameters = {"ios_attachments" : {"image1" : "{image_url}"}};
let data = arr // some array as payload
let contents = {
	'en': 'You got notification from user'
}
OneSignal.postNotification(contents, data, playerId, otherParameters);

// Listening to postNotification using OneSignal.Configure:
onNotificationOpened: function(message, data, isActive) {
	if (data.p2p_notification) {
		for (var num in data.p2p_notification) {
			// console.log(data.p2p_notification[num]);
		}
	}
}

Prompt Location

We exposed the promptLocation API of OneSignal.

Prompts the user for location permissions. This allows for geotagging so you can send notifications to users based on location.

Note: Make sure you also have the required location permission in your AndroidManifest.xml. For iOS, make sure you set the NSLocationWhenInUseUsageDescription or the NSLocationAlwaysUsageDescription in your info.plist. (Location Always also requires the location background mode capability)

// Calling promptLocation
OneSignal.promptLocation();

setLocationShared

Disable or enable location collection (defaults to enabled if your app has location permission).

OneSignal.setLocationShared(false);

Clear Notifications (Android Only)

We exposed the clearOneSignalNotifications API of OneSignal (currently supported only on Android).

Removes all OneSignal notifications from the Notification Shade.

// Calling clearOneSignalNotifications
OneSignal.clearOneSignalNotifications();

Cancel Notifications (Android Only)

We exposed the cancelNotification API of OneSignal (currently supported only on Android).

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

Check Push Notification Permissions (iOS Only)

See what push permissions are currently enabled. callback will be invoked with a permissions object (currently supported only on iOS).

// Requesting permissions
OneSignal.checkPermissions((permissions) => {
	console.log(permissions);
});

Request Push Notification Permissions (iOS Only)

We exposed the requestPermissions method (currently supported only on iOS).

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

Register For Push Notifications (iOS Only)

We exposed the registerForPushNotifications API of OneSignal (currently supported only on iOS).

*Call when you want to prompt the user to accept push notifications. Only call once and only if you passed @NO to kOSSettingsKeyAutoPrompt on init.

// Calling registerForPushNotifications
OneSignal.registerForPushNotifications();

The following example is from our own App and needs to be customized in order to work.

Example:

_syncOneSignal = () => {
	var allTags = {};
	var missingTags = {};

	OneSignal.getTags((receivedTags) => {
		// Find missing tags
		for (var i = this.categories.length * 1; i >= 0; i--) {
			var category = this.categories[i];
			if (!(category.slug in receivedTags)) {
				missingTags[category.slug] = category.is_push_default;
			}
			// Hash all tags for performance later on deletion
			allTags[category.slug] = category.is_push_default;
		};

		// Send missing tags if there are any
		if (Object.keys(missingTags).length > 0) {
			OneSignal.sendTags(missingTags);
		}

		// Delete tags that doesn't show up in the categories
		Object.keys(receivedTags).forEach(function(key,index) {
		    if (!(key in allTags)) {
		    	OneSignal.deleteTag(key);
		    }
		});
	});
};

GDPR Consent Functions

setRequiresUserPrivacyConsent

Allows you to delay the initialization of the SDK until the user provides privacy consent. The SDK will not be fully initialized until the provideUserConsent(true) method is called.

If you set this to be true, the SDK will not fully initialize until consent is provided. You can still call OneSignal methods, but nothing will happen, and the user will not be registered for push notifications.

componentWillMount() {
  // Will delay initialization of the SDK until the user provides consent
  OneSignal.setRequiresUserPrivacyConsent(true);
  OneSignal.init("YOUR_ONESIGNAL_APPID");
}

provideUserConsent
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.

function userTappedProvideConsentButton() {
  // Will initialize the SDK and register for push notifications
  OneSignal.provideUserConsent(true);
}

Debugging

setLogLevel

Enable logging to help debug if you run into an issue setting up OneSignal. The logging levels are available with increasingly more information, as follows:
0 = None
1 = Fatal
2 = Errors
3 = Warnings
4 = Info
5 = Debug
6 = Verbose

Parameters
Type
Description

logLevel

Integer

Sets the logging level to print to the iOS Xcode log or the Android LogCat log.

visualLevel

Integer

Sets the logging level to show as alert dialogs.

OneSignal.setLogLevel(6, 0);