Skip to content

Integrating the Braze React Native SDK

This reference article covers how to install the Braze SDK for React Native. Installing the Braze React Native SDK provides basic analytics functionality and lets you integrate in-app messages and Content Cards for both iOS and Android with just one codebase.

Prerequisites

To integrate the SDK, React Native version 0.71 or later is required. For the full list of supported versions, see our React Native SDK GitHub repository.

New Architecture compatibility

The following minimum SDK version is compatible with all apps using React Native’s New Architecture:

Starting with SDK version 6.0.0, Braze uses a React Native Turbo Module, which is compatible with both the New Architecture and legacy bridge architecture—meaning no additional setup is required.

Integrating the SDK

Step 1: Integrate the Braze library

1

npm install @braze/react-native-sdk

1

yarn add @braze/react-native-sdk

Step 2: Choose a setup option

You can manage the Braze SDK using the Braze Expo plugin or through one of the native layers. With the Expo plugin, you can configure certain SDK features without writing code in the any of native layers. Choose whichever option best meets your app’s needs.

Step 2.1: Install the Braze Expo plugin

Ensure that your version of the Braze React Native SDK is at least 1.37.0. For the full list of supported versions, check out the Braze React Native repository.

To install the Braze Expo plugin, run the following command:

1

expo install @braze/expo-plugin

Step 2.2: Add the plugin to your app.json

In your app.json, add the Braze Expo Plugin. You can provide the following configuration options:

Example configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          "androidApiKey": "YOUR-ANDROID-API-KEY",
          "iosApiKey": "YOUR-IOS-API-KEY",
          "baseUrl": "YOUR-SDK-ENDPOINT",
          "sessionTimeout": 60,
          "enableGeofence": false,
          "enableBrazeIosPush": false,
          "enableFirebaseCloudMessaging": false,
          "firebaseCloudMessagingSenderId": "YOUR-FCM-SENDER-ID",
          "androidHandlePushDeepLinksAutomatically": true,
          "enableSdkAuthentication": false,
          "logLevel": 0,
          "minimumTriggerIntervalInSeconds": 0,
          "enableAutomaticLocationCollection": false,
          "enableAutomaticGeofenceRequests": false,
          "dismissModalOnOutsideTap": true,
          "androidPushNotificationHtmlRenderingEnabled": true,
          "androidNotificationAccentColor": "#ff3344",
          "androidNotificationLargeIcon": "@drawable/custom_app_large_icon",
          "androidNotificationSmallIcon": "@drawable/custom_app_small_icon",
          "iosRequestPushPermissionsAutomatically": false,
          "enableBrazeIosPushStories": true,
          "iosPushStoryAppGroup": "group.com.example.myapp.PushStories"
        }
      ],
    ]
  }
}

Step 2.3: Build and run your application

Prebuilding your application will generate the native files necessary for the Braze Expo plugin to work.

1

expo prebuild

Run your application as specified in the Expo docs. Keep in mind, if you make any changes to the configuration options, you’ll be required to prebuild and run the application again.

Step 2.1: Add our repository

In your top-level project build.gradle, add the following under buildscript > dependencies:

1
2
3
4
5
6
7

buildscript {
    dependencies {
        ...
        // Choose your Kotlin version
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.10")
    }
}

This will add Kotlin to your project.

Step 2.2: Configure the Braze SDK

To connect to Braze servers, create a braze.xml file in your project’s res/values folder. Paste the following code and replace the API key and endpoint with your values:

1
2
3
4
5

<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_braze_api_key">YOU_APP_IDENTIFIER_API_KEY</string>
<string translatable="false" name="com_braze_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
</resources>

Add the required permissions to your AndroidManifest.xml file:

1
2

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Step 2.3: Implement user session tracking

The calls to openSession() and closeSession() are handled automatically. Add the following code to the onCreate() method of your MainApplication class:

1
2
3
4
5
6
7
8

import com.braze.BrazeActivityLifecycleCallbackListener;

@Override
public void onCreate() {
    super.onCreate();
    ...
    registerActivityLifecycleCallbacks(new BrazeActivityLifecycleCallbackListener());
}

1
2
3
4
5
6
7

import com.braze.BrazeActivityLifecycleCallbackListener

override fun onCreate() {
    super.onCreate()
    ...
    registerActivityLifecycleCallbacks(BrazeActivityLifecycleCallbackListener())
}

Step 2.4: Handle intent updates

If your MainActivity has android:launchMode set to singleTask, add the following code to your MainActivity class:

1
2
3
4
5

@Override
public void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
}

1
2
3
4

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
}

Step 2.1: (Optional) Configure Podfile for dynamic XCFrameworks

To import certain Braze libraries, such as BrazeUI, into an Objective-C++ file, you will need to use the #import syntax. Starting in version 7.4.0 of the Braze Swift SDK, binaries have an optional distribution channel as dynamic XCFrameworks, which are compatible with this syntax.

If you’d like to use this distribution channel, manually override the CocoaPods source locations in your Podfile. Reference the sample below and replace {your-version} with the relevant version you wish to import:

1
2
3

pod 'BrazeKit', :podspec => 'https://raw.githubusercontent.com/braze-inc/braze-swift-sdk-prebuilt-dynamic/{your-version}/BrazeKit.podspec'
pod 'BrazeUI', :podspec => 'https://raw.githubusercontent.com/braze-inc/braze-swift-sdk-prebuilt-dynamic/{your-version}/BrazeUI.podspec'
pod 'BrazeLocation', :podspec => 'https://raw.githubusercontent.com/braze-inc/braze-swift-sdk-prebuilt-dynamic/{your-version}/BrazeLocation.podspec'

Step 2.2: Install pods

Since React Native automatically links the libraries to the native platform, you can install the SDK with the help of CocoaPods.

From the root folder of the project:

1
2
3
4
5

# To install using the React Native New Architecture
cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

# To install using the React Native legacy architecture
cd ios && pod install

Step 2.3: Configure the Braze SDK

Import the Braze SDK at the top of the AppDelegate.swift file:

1

import BrazeKit

In the application(_:didFinishLaunchingWithOptions:) method, replace the API key and endpoint with your app’s values. Then, create the Braze instance using the configuration, and create a static property on the AppDelegate for easy access:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
) -> Bool {
    // Setup Braze
    let configuration = Braze.Configuration(
        apiKey: "{BRAZE_API_KEY}",
        endpoint: "{BRAZE_ENDPOINT}")
    // Enable logging and customize the configuration here.
    configuration.logger.level = .info
    let braze = BrazeReactBridge.perform(
      #selector(BrazeReactBridge.initBraze(_:)),
      with: configuration
    ).takeUnretainedValue() as! Braze

    AppDelegate.braze = braze

    /* Other configuration */

    return true
}

// MARK: - AppDelegate.braze

static var braze: Braze? = nil

Import the Braze SDK at the top of the AppDelegate.m file:

1
2

#import <BrazeKit/BrazeKit-Swift.h>
#import "BrazeReactBridge.h"

In the application:didFinishLaunchingWithOptions: method, replace the API key and endpoint with your app’s values. Then, create the Braze instance using the configuration, and create a static property on the AppDelegate for easy access:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Setup Braze
  BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:@"{BRAZE_API_KEY}"
                                                                    endpoint:@"{BRAZE_ENDPOINT}"];
  // Enable logging and customize the configuration here.
  configuration.logger.level = BRZLoggerLevelInfo;
  Braze *braze = [BrazeReactBridge initBraze:configuration];
  AppDelegate.braze = braze;

  /* Other configuration */

  return YES;
}

#pragma mark - AppDelegate.braze

static Braze *_braze = nil;

+ (Braze *)braze {
  return _braze;
}

+ (void)setBraze:(Braze *)braze {
  _braze = braze;
}

Step 3: Import the library

Next, import the library in your React Native code. For more details, check out our sample project.

1

import Braze from "@braze/react-native-sdk";

Step 4: Test the integration (optional)

To test your SDK integration, start a new session on either platform for a user by calling the following code in your app.

1

Braze.changeUser("userId");

For example, you can assign the user ID at the startup of the app:

1
2
3
4
5
6
7
8
9
10
11
12
13

import React, { useEffect } from "react";
import Braze from "@braze/react-native-sdk";

const App = () => {
  useEffect(() => {
    Braze.changeUser("some-user-id");
  }, []);

  return (
    <div>
      ...
    </div>
  )

In the Braze dashboard, go to User Search and look for the user with the ID matching some-user-id. Here, you can verify that session and device data were logged.

Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!