SDK integration

Note: If you’re using Expo, make sure you eject to the bare workflow to implement Batch.

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

Integrating the SDK

Install the plugin, using yarn:

yarn add @bam.tech/react-native-batch

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 
Installing RNBatchPush

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 @bam.tech/react-native-batch
  • 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/@bam.tech/react-native-batch/iOS'`
  • Install the pods:

cd ios
pod install

Setting up your APIKey

  • On iOS, look for your Info.plist and add the following:
<key>BatchAPIKey</key>
<string>YOUR_BATCH_API_KEY</string>
  • 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

Install Batch dependencies

Setup the required dependencies in Gradle scripts:

// android/build.gradle

buildscript {
    ...
    ext {
        batchSdkVersion = '1.17+'
    }
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.3.4'
    }
}
// android/app/build.gradle

dependencies {
    implementation platform('com.google.firebase:firebase-bom:25.12.0') // needed if you don't have @react-native-firebase/app
    implementation "com.google.firebase:firebase-messaging" // needed if you don't have @react-native-firebase/messaging
    implementation "com.batch.android:batch-sdk:${rootProject.ext.batchSdkVersion}"
    ...
}

apply plugin: 'com.google.gms.google-services'

Configure auto-linking

Create or adapt the react-native.config.js file at the root of your project:

// react-native.config.js

module.exports = {
  dependencies: {
    '@bam.tech/react-native-batch': {
      platforms: {
        android: {
          packageInstance: 'new RNBatchPackage(this.getApplication())',
        },
      },
    },
  },
};

Add you Firebase config

Add the google-services.json file to /android/app

Configure onNewIntent

Add the following in your MainActivity.java:

// import android.content.Intent;
// import com.batch.android.Batch;

@Override
public void onNewIntent(Intent intent)
{
    Batch.onNewIntent(this, intent);
    super.onNewIntent(intent);
}

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 ...>
        <meta-data
            android:name="com.batch.android.push.smallicon"
            android:resource="@drawable/push_icon" />

        <!-- Notification color. ARGB but the alpha value can only be FF -->
        <meta-data
            android:name="com.batch.android.push.color"
            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.

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];
    ...
    return YES;
}

Setup your UNUserNotificationCenterDelegate

  • If you use Firebase or another framework swizzling your AppDelegate, follow the manual integration guide.

  • Otherwise, add the following in your AppDelegate.m:


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    [RNBatch start];
    [BatchUNUserNotificationCenterDelegate registerAsDelegate];
    //[BatchUNUserNotificationCenterDelegate sharedInstance].showForegroundNotifications = true;
    ...
    return YES;
}

If you want to show foreground notifications, add the relevant configuration: [BatchUNUserNotificationCenterDelegate sharedInstance].showForegroundNotifications = true; after registering the delegate .

Enable push notifications

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

import { BatchPush } from '@bam.tech/react-native-batch';

// 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.
BatchPush.registerForRemoteNotifications();

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.