JourneysUsersSDKIntegrations
Log InSign Up

React Native SDK Setup

Instructions for adding the OneSignal React Native & Expo SDK to your app for iOS, Android, and derivatives like Amazon

Suggest Edits

Requirements

iOS Requirements

Android Requirements

Amazon & Huawei Requirements

Setup

1. Add SDK

Add the react-native-onesignal package to your project.

  • Yarn: yarn add react-native-onesignal
  • npm npm install --save react-native-onesignal

Skip this next command if you are using React Native version higher than0.60+ because Autolinking is now done automatically.

  • Only for React Native 0.60 or less: react-native link react-native-onesignal

2. iOS Setup

Open the .xcworkspace file in Xcode located your project's iOS folder.

Select the root project > your main app target and "Signing & Capabilities".

If you do not see Push Notifications enabled, click "+ Capability" and add "Push Notifications".

2624

Click "+ Capability" and add "Background Modes". Then check "Remote notifications".

2762

Add Notification Service Extension

The OneSignalNotificationServiceExtension allows your iOS application to receive rich notifications with images, buttons, and badges. It's also required for OneSignal's Confirmed Delivery analytics features.

In Xcode Select File > New > Target...
Select Notification Service Extension then Next.

1472

Enter the product name as OneSignalNotificationServiceExtension and press Finish.

1472

Do not activate the scheme on the dialog that is shown after selecting Finish.

Press Cancel on the Activate scheme prompt.

300

By canceling, you are keeping Xcode debugging your app, instead of the extension you just created.

If you activated by accident, you can switch back to debug your app within Xcode (next to the play button).

In the project navigator, select the top-level project directory and select the OneSignalNotificationServiceExtension target in the project and targets list.

Ensure the Deployment Target is set to the same value as your Main Application Target. Unless you have a specific reason not to, you should set the Deployment Target to be iOS 11 or above.

2536

This should be the same value as your Main Application Target.

In the project navigator, click the OneSignalNotificationServiceExtension folder and open the NotificationService.swift or NotificationService.m and replace the whole file's contents with the following code. Ignore any build errors at this point. We will import OneSignal which will resolve any errors. 

import UserNotifications

import OneSignalExtension

class NotificationService: UNNotificationServiceExtension {
    
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?
    
    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        
        if let bestAttemptContent = bestAttemptContent {
            /* DEBUGGING: Uncomment the 2 lines below to check this extension is executing
                          Note, this extension only runs when mutable-content is set
                          Setting an attachment or action buttons automatically adds this */
            // print("Running NotificationServiceExtension")
            // bestAttemptContent.body = "[Modified] " + bestAttemptContent.body
            
            OneSignalExtension.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }
    
    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            OneSignalExtension.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }  
}

#import <OneSignalExtension/OneSignalExtension.h>

#import "NotificationService.h"

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNNotificationRequest *receivedRequest;
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.receivedRequest = request;
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    /* DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is executing
                  Note, this extension only runs when mutable-content is set
                  Setting an attachment or action buttons automatically adds this */
    // NSLog(@"Running NotificationServiceExtension");
    // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];
    
    [OneSignalExtension didReceiveNotificationExtensionRequest:self.receivedRequest
                       withMutableNotificationContent:self.bestAttemptContent
                                   withContentHandler:self.contentHandler];
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    
    [OneSignalExtension serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
    
    self.contentHandler(self.bestAttemptContent);
}

@end

Ignore any build errors at this point. We will import OneSignal which will resolve any errors.

Add App Groups

App Groups allow your app and the OneSignalNotificationServiceExtension to communicate when a notification is received, even if your app is not active. This is required for badges and Confirmed Deliveries.

  1. In your Main App Target
  2. Go to "Signing & Capabilities" > "All"
  3. Click "+ Capability" if you do not have App Groups in your app yet
  4. Select App Groups
  1. Under App Groups click the "+" button
  2. Set the "App Groups" container to be group.YOUR_BUNDLE_IDENTIFIER.onesignal where YOUR_BUNDLE_IDENTIFIER is the same as set in "Bundle Identifier"
  3. Press OK
  1. In the OneSignalNotificationServiceExtension Target
  2. Go to "Signing & Capabilities" > "All"
  3. Click "+ Capability" if you do not have App Groups in your app yet
  4. Select App Groups
  1. Under App Groups click the "+" button
  2. Set the "App Groups" container to be group.YOUR_BUNDLE_IDENTIFIER.onesignal where YOUR_BUNDLE_IDENTIFIER is the same as your Main App Target "Bundle Identifier". Do Not Include OneSignalNotificationServiceExtension
  3. Press OK

Setup OneSignal key in .plist

This step is only required if you do not want to use the default app group name (which is group.{your_bundle_id}.onesignal).

1. Open your Info.plist file and add a new OneSignal_app_groups_key as a String type.
2. Enter the group name you checked in the last step as it's value.
3. Make sure to do the same for the Info.plist under the OneSignalNotificationServiceExtension folder.

In the /ios directory of your project, open the Podfile and add the following outside of the main target (should be at the same level as your main target):

target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 5.0.0', '< 6.0'
end

From your terminal, navigate to this ios folder and run pod install --repo-update

3. Android Setup

By default, notifications will be shown with a small bell icon in the notification shade. Follow the Customize Notification Icons guide to create your own small and large notification icons for your app.

4. Initialization

In your App.js or index.js initialize OneSignal and try the example methods below:

import { LogLevel, OneSignal } from 'react-native-onesignal';

// Remove this method to stop OneSignal Debugging
OneSignal.Debug.setLogLevel(LogLevel.Verbose);

// OneSignal Initialization
OneSignal.initialize("ONESIGNAL_APP_ID");

// requestPermission will show the native iOS or Android notification permission prompt.
// We recommend removing the following code and instead using an In-App Message to prompt for notification permission
OneSignal.Notifications.requestPermission(true);

// Method for listening for notification clicks
OneSignal.Notifications.addEventListener('click', (event) => {
  console.log('OneSignal: notification clicked:', event);
});

🚧

Event Listeners & Components

We suggest using a base/root component to add as an event listener. If you choose a sub-component that is only shown in some situations (such as using a homepage as an event listener), the component may unmount later on as the user navigates elsewhere in your app.

If you encounter problems with one or more of the events listeners, please see our troubleshooting documentation here.

5. Testing

Run your app on a physical device to make sure it builds correctly.

If you used the provided code, then the requestPermission method, should prompt you to subscribe to push notifications. You can change this later.

Check your OneSignal Dashboard Audience > Subscriptions to see your User & Subscription Record.

Then head over to Messages > New Push to Send your first Push Notification from OneSignal.

📘

Troubleshooting

If running into issues, see our Mobile Troubleshooting Guide.

Try our example projects on our Github repository.

If stuck, contact support directly or email [email protected] for help.

For faster assistance, please provide:

  • Your OneSignal App ID
  • Details, logs, and/or screenshots of the issue
  • Steps to reproduce

Recommended

Push permission with In-App Message

You can continue to opt-in users to push via the requestPermission method. However, Apple's Human Interface Guidelines recommends that apps "Create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out."

OneSignal provides In-App Messages to meet this recommendation and create a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt is limited to how many times it can show and cannot be shown again if the user clicks deny.

See How to Prompt for Push Permissions with In-App Messages for details on implementing this.

Identify Users

Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).

OneSignal creates subscription-level records under a unique ID called the subscription_id. A single user can have multiple subscription_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.

If your app has its own login system to track users, call login at any time to link all channels to a single user. For more details, see Aliases & External ID.

let externalId = "123456789" // You will supply the external id to the OneSignal SDK
OneSignal.login(externalId);

Set Email & Phone Number

Recommended for messaging across multiple channels (push, email, sms).

Use the provided SDK methods to capture one or more email/phone numbers for the user. Follow the channel quickstart guides for setup:

// Pass in email provided by customer
OneSignal.User.addEmail("[email protected]");

// Pass in phone number provided by customer
OneSignal.User.addSms("+11234567890");

Add Data Tags

Optional

Tags are custom key : value pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.

OneSignal.User.addTag("key", "value");

Advanced

Manually Updating Native iOS SDK

When you install react-native-onesignal it will automatically include a specific version of the OneSignal iOS native SDK that is known to work with it. Only follow the instructions below if there is a native OneSignal SDK fix you need that isn't included already in the latest react-native-onesignal update.

  1. Download the latest OneSignal iOS native release
  2. Delete libOneSignal.a and OneSignal.h from node_modules/react-native-onesignal/ios/
  3. From /iOS_SDK/OneSignalSDK/Framework/OneSignal.framework/Versions/A/, copy OneSignal to /node_modules/react-native-onesignal/ios/ and rename it libOneSignal.a
  4. Copy OneSignal.h from /iOS_SDK/OneSignalSDK/Framework/OneSignal.framework/Versions/A/Headers to /node_modules/react-native-onesignal/ios/

Updated 9 days ago

What’s Next