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

Step-by-Step React Native 3.x to 4.0.0 Upgrade Guide

Step 1 - Requirements

This guide assumes you already have setup the react-native-onesignal 3.x.x and are migrating your app to the 4.x Major version.


Upgrade to min version React Native 0.60 for AndroidX Support

AndroidX is a now requirement to use the new react-native-onesignal 4.0+ SDK.

Learn more

Step 2 - Upgrade to Version 4

In your package.json, update the npm package version

"dependencies": {
    "react-native-onesignal": "^4.0.6"

In your Podfile, update the OneSignalNotificationServiceExtension

target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignal', '>= 3.4.1', '< 4.0'


Make sure to install the npm package as well as update the Pod used in the ios directory of your project.

npm install # or yarn install
cd ios
pod update OneSignal

Step 3 - Update initialization code

3.1 Open your main file (e.g: App.js)
3.2 Replace the following

// OneSignal Initialization
OneSignal.init("YOUR_ONESIGNAL_APP_ID", {kOSSettingsKeyAutoPrompt : false, kOSSettingsKeyInAppLaunchURL: false, kOSSettingsKeyInFocusDisplayOption:2});

With the new initialization:

// OneSignal Initialization

For any iOS settings you had previously, note that:

  • kOSSettingsKeyAutoPrompt is deprecated. If you omitted this previously or set it to true, you will now need to prompt the user by calling promptForPushNotificationsWithUserResponse().
  • kOSSettingsKeyInAppLaunchURL is deprecated. There is currently no replacement for it.
  • kOSSettingsKeyInFocusDisplayOption is replaced by adding a NotificationWillShowInForegroundHandler (see below).

3.3 Review your existing inFocusDisplaying() usage.

  • This was most likely set to 2 which means no additional changes need as this is the default in 4.x. Simply remove the function call.
  • If you didn't have inFocusDisplaying at all in your code or this was set to 0 the replacement for this is adding a NotificationWillShowInForegroundHandler.

Step 4 - Update Event Listeners

If you have event-listeners set up, you will need to switch to use the new handlers & observer setter functions.

See handlers & observers reference for more details.

version 3.0+ event stringversion 4.0+ event handler / observer

The equivalent of the "received" event listener is the new NotificationWillShowInForegroundHandler. You can use this to have better notification foreground control as well as get notification-specific data before it is displayed to the user while the app is in focus.

Step 5 - Review Full List

:white-check-mark: You're setup with the new SDK!
Please review the full 4.0 API Reference - React Native for a full list of new and deprecated features as well as other advanced features you may need to migrate as well.

Updated 19 days ago

Step-by-Step React Native 3.x to 4.0.0 Upgrade Guide

Suggested Edits are limited on API Reference Pages

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