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 Setup

OneSignal React Native SDK Setup Guide. Works with iOS, Android, and derivatives like Amazon.

Required For Setup


If you are using Expo, you will have to detach in order to complete the following steps.

Generate Credentials

Before setting up the React Native SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:

iOS - Generate an iOS Push Certificate

Android - Generate a Google Server API Key

Amazon - Generate an Amazon API Key

Running Example project

For your convenience, we created an example project, based on React Native 0.41.2.
You can run this project to test configurations, debug, and build upon it.

  • git clone
  • cd react-native-onesignal && cd examples && cd RNOneSignal
  • yarn
  • Running the Android example app: react-native run-android
  • Running the iOS example app:
    • Open the RNOneSignal project in XCode
    • Change the Signing Team and Bundle Identifier for both the RNOneSignal target as well as the OneSignalNotificationServiceExtension
      • The Service Extension bundle id should be <main-target-bunde-id>.OneSignalNotificationServiceExtension
    • Build

1. Installation

1.1 Add OneSignal

  • yarn add react-native-onesignal
  • OR npm install --save react-native-onesignal

1.2 Link OneSignal

react-native link react-native-onesignal

Manual Linking - React Native 0.59.0 Older & Not Using Cocoapods

If you are not using Cocoapods AND react-native link react-native-onesignal does not work

  • Add RCTOneSignal project into Libraries manually (screenshot):
    • Open node_modules/react-native-onesignal/ios
    • Then, drag and drop RCTOneSignal.xcodeproj into XCode project folder Libraries

1.3 Cocoapods Install (iOS Only)

Run cd ios && pod install && cd ..

Android Specific Instructions

In your AndroidManifest.xml, add android:launchMode="singleTop" as an attribute to your main activity.


<application ....>
    android:label="OneSignal Example"
    android:launchMode="singleTop"> <!-- Add this attribute to your main activity -->

NOTE: We've recently added JavaScript react-native initialization of the SDK. You no longer need to add your App ID to the app gradle file. Please see Initializing the SDK for details.

Adding the Gradle Plugin

1. At the very top of your Android project's app/build.gradle, add the following code to the very top of the file:

buildscript {
    repositories {
        maven { url '' } // Gradle Plugin Portal 
    dependencies {
        classpath '[0.12.1, 0.99.99]'

apply plugin: 'com.onesignal.androidsdk.onesignal-gradle-plugin'

2. Inside of the android { ... } section in your app/build.gradle, please ensure that your compileSdkVersion and buildToolsVersion is at least API level 26 or higher

android {
    compileSdkVersion 27
    buildToolsVersion '27.0.3'
    // ...

AndroidX Migration

Required for projects running React Native 0.60.0+
The OneSignal SDK is not yet upgraded to AndroidX. Luckily, Google created a tool called Jetifier that will migrate the imports, even for compiled .jar.

In the meantime, there is an easier way to add Jetifier than following Google's guide above. You can add an npm package called jetifier, noted from React Native 0.60.0 release notes.

iOS Installation

iOS Push Certificate

Add Required Capabilities

  1. Select the root project and Under Capabilities Enable "Push Notifications".
  2. Next Enable "Background Modes" and check "Remote notifications".

Add Notification Service Extension

Required for Incrementing Badge count

You will need Notification Service Extension to increment badge counts using App Groups setup below

This step is optional but highly recommended. The OneSignalNotificationServiceExtension allows your application (in iOS) to receive rich notifications with images and/or buttons. If you do not follow this step, your application will not be able to show images in push notifications, and won't be able to add action buttons to notifications either.

Even if you do not have immediate plans to send push notifications containing images/action buttons, it is still recommended to follow these steps in case you ever decide to change your mind in the future.

  • In Xcode, select File > New > Target
  • Select Notification Service Extension and press Next


  • Enter the product name as OneSignalNotificationServiceExtension, we recommend using the Language as Objective-C
  • Press Finish


  • Press Cancel on the Activate Scheme prompt


By cancelling, you are telling Xcode to continue debugging your application, instead of debugging just the extension. If you activate by accident, you can always switch back to debug your app in Xcode by selecting your application's target (next to the Play button)

Finish Notification Service Extension Setup

If you did not use Cocoapods, follow these steps.

Otherwise, continue with the following setup:

  • In your Podfile, add the notification service extension:
target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignal', '>= 2.9.3', '< 3.0'

Make sure to run pod install again.

  • Open NotificationService.m or NotificationService.swift and replace the whole file contents with the code below:
#import <OneSignal/OneSignal.h>

#import "NotificationService.h"

@interface NotificationService ()

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


@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.receivedRequest = request;
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];
    // DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is excuting
    //            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];

- (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.
    [OneSignal serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

import UserNotifications

import OneSignal

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
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
        if let bestAttemptContent = bestAttemptContent {
            OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: self.bestAttemptContent)
    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 {
            OneSignal.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)

Swift Bridging Header

If you are using Swift, make sure to create a separate Objective-C Bridging Header for your OneSignalNotificationExtensionService and add the following import:

#import "RCTOneSignalExtensionService.h"

Then you need to tell your Xcode project settings what your bridging header is named, like this.

Ignore any build errors at this point, the next step will import OneSignal which will resolve any errors.

Add App Groups (Optional but Recommended)

In order for your application to be able to let push notifications increment/decrement the badge count, you need to set up an App Group for your application.

Please follow this guide to set up a OneSignal app group in your app.

Initializing the SDK

Both Platforms

OneSignal's react-native SDK now supports JavaScript initialization directly in react native, without having to write native Objective-C code or mess with gradle files.

Native Initialization

While we now support initialization directly in javascript/react, you can still use the older native initialization methods (Objective-C and gradle for iOS and Android respectively). We recommend against doing this, but it is still supported. For information on how to do this, you can read our old readme.

In order to initialize the SDK:

constructor(properties) {

You can also pass in parameters for iOS. These parameters will simply be ignored in Android.

For a full list of supported iOS settings, please see our API reference documentation.

constructor(properties) {
  OneSignal.init("YOUR_ONESIGNAL_APPID", {kOSSettingsKeyAutoPrompt : true});


In your App.js or index.js:

import React, { Component } from 'react';
import OneSignal from 'react-native-onesignal'; // Import package from node modules

export default class App extends Component {

constructor(properties) {
    OneSignal.init("YOUR_ONESIGNAL_APPID", {kOSSettingsKeyAutoPrompt : true});// set kOSSettingsKeyAutoPrompt to false prompting manually on iOS

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

  componentWillUnmount() {
    OneSignal.removeEventListener('received', this.onReceived);
    OneSignal.removeEventListener('opened', this.onOpened);
    OneSignal.removeEventListener('ids', this.onIds);

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

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

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.

Manually updating iOS OneSignalNativeSDK

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/


If you are having trouble with our SDK, please see our Troubleshooting guide.

Updated 12 days ago

React Native SDK Setup

OneSignal React Native SDK Setup Guide. Works with iOS, Android, and derivatives like Amazon.

Suggested Edits are limited on API Reference Pages

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