SDK integration

Note: Batch doesn't work with Expo, as it depends on native components which are not supported by Expo. Please use standard React Native, or eject to the bare workflow.

This guide assumes that you've already followed the iOS and Android prerequisites.

Integrating the SDK

Install the plugin, using yarn:

yarn add

React Native >= 0.60.0

Recent versions of React Native automatically link native libraries.

Installing the pods is still required:

cd ios
pod install

You should see the following logs:

Auto-linking React Native module for target `Sample`: RNBatchPush
Analyzing dependencies
Downloading dependencies
Installing Batch (1.16.0)
Installing RNBatchPush (1.0.0)

React Native < 0.60.0

Older versions of React Native do not support auto linking, it must be done manually:

  • First, link the library:
react-native link
  • cd into the ios folder

  • Edit Podfile:

    • Find the line that begins with pod 'RNBatchPush' and delete it (it might not exist)
    • Add the following line:
    pod 'RNBatchPush', :path => '../node_modules/'`
  • Install the pods:

cd ios
pod install

Starting the SDK

Add the following in your app code, ideally the first view a user sees when opening the app:

import { Batch, BatchPush } from '';


// This method triggers iOS' notification authorization popup
// If you want to ask for notifications at a later date, don't execute this on the first run
// but make sure you call this on every app start after asking for the permission,
// so that Batch always gets the latest push token, preventing delivery issues.

Setting up your APIKey

  • On iOS, look for your Info.plist and add the following:
  • On Android, open android/app/build.gradle and add:
defaultConfig {
    resValue "string", "BATCH_API_KEY", "YOUR_BATCH_API_KEY"

YOUR_BATCH_API_KEY is your Batch Dev or Live API key. You'll find the API keys needed to set up the SDK in Settings → General:

  • Dev API key: Use it for development or testing purposes. This API key won't trigger stats computation. Please take care not to ship an app on a Store with this API key.
  • Live API key: Should be used in a production environment only and in the final version of your app on the Store.

If you created different apps on the Batch dashboard for testing purposes, you can use the Live Api Key.

Android specific steps

  • Setup the required dependencies in Gradle scripts:
// android/build.gradle

buildscript {
    dependencies {
        classpath ''

// android/app/build.gradle

dependencies {
    implementation ""
    implementation ""

apply plugin: ''
  • Add the google-services.json file to /android/app

Small push notification icon

For better results on Android 5.0 and higher, it is recommended to add a Small Icon and Notification Color. An icon can be generated using Android Studio's asset generator: as it will be tinted and masked by the system, only the alpha channel matters and will define the shape displayed. It should be of 24x24dp size. If your notifications shows up in the system statusbar in a white shape, this is what you need to configure.

This can be configured in the manifest as metadata in the application tag:

<!-- Assuming there is a push_icon.png in your res/drawable-{dpi} folder -->

<manifest ...>
    <application ...>
            android:resource="@drawable/push_icon" />

        <!-- Notification color. ARGB but the alpha value can only be FF -->
            android:value="#FF00FF00" />

iOS specific steps

Enable Push Capabilities

Open the xcworkspace in the ios/ folder. In the project window:

  • Select your project in the sidebar
  • Go to Signing & Capabilities
  • Press on + Capability
  • Add Push Notifications

Start the SDK natively

Starting with 5.2.1, due to how iOS' app lifecycle works, Batch must be started natively. The javascript start method is a no-op on iOS.

Add the following to your application delegate:

#import <RNBatchPush/RNBatch.h>
// or, use #import "RNBatch.h" if the framework import didn't work

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    [RNBatch start:false]; // or true if you want the do not disturb mode
    return YES;

Your first notification

1. Obtaining Your Device Token on iOS

You can find your device's token using the debug tool or locating the token Batch posts to the Xcode console:

Push token (Apple Push Production): <push token>

Based on your Provisioning Profile, the token shown in the console will be Development ("Sandbox/Development") or Production ("Production").

2. Obtaining Your Device Token on Android

You can find your device's token using the debug tool or locating the token Batch posts to the logcat (see here to know more):

Batch.Push: Registration ID/Push Token (FCM): <your device token>

3. Sending A Test Push

You can send test notifications to your device with a push token. In the push notification creation form, click the ⚙️ and copy your push token in the corresponding field. Hit "Send a test".

Test push

What's next

Congratulations on finishing the integration of Batch Push!

Here are a couple of extra steps you can take before releasing your app:

  • Live API key: Ensure you don't use Batch's DEV API key in the build you will upload to the AppStore / Play Store.
  • Small icon / Accent color: On Android, make sure the small icon you are using is opaque white. We also recommend you use an accent color.
  • Custom user identifier: Add support for custom user identifiers if you are planning to use the Transactional or the Custom Data APIs.
  • Token import: Import your existing tokens if you're coming from another push provider.