Skip to content

Initial SDK setup

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.

You will need to complete installation steps on both platforms separately.

To complete the installation, you will need the app identifier API key as well as the SDK endpoint. Both are located under Manage Settings in the dashboard.

Prerequisites and compatibility

Braze React Native SDK v1.38.0+:

  • Supports React Native v0.64+

React Native New Architecture Support

  • React Native v0.68+
  • Braze React Native SDK v2.0.1+

Step 1: Integrate the Braze library

1

npm install @braze/react-native-sdk

1

yarn add @braze/react-native-sdk

Step 2: Complete native setup

Step 2.1: Install the Braze Expo plugin

Ensure that your version of the Braze React Native SDK is at least 1.37.0. Then, install the Braze Expo plugin.

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:

Method Type Description
androidApiKey string Required. The API key for your Android application.
iosApiKey string Required. The API key for your iOS application.
baseUrl string Required. The SDK endpoint for your application.
enableBrazeIosPush boolean iOS only. Whether to use Braze to handle push notifications on iOS. Introduced in React Native SDK v1.38.0 and Expo Plugin v0.4.0.
enableFirebaseCloudMessaging boolean Android only. Whether to use Firebase Cloud Messaging for push notifications. Introduced in React Native SDK v1.38.0 and Expo Plugin v0.4.0.
firebaseCloudMessagingSenderId string Android only. Your Firebase Cloud Messaging sender ID. Introduced in React Native SDK v1.38.0 and Expo Plugin v0.4.0.
sessionTimeout integer The Braze session timeout for your application in seconds.
enableSdkAuthentication boolean Whether to enable the SDK Authentication feature.
logLevel integer The log level for your application. The default log level is 8 and will minimally log info. To enable verbose logging for debugging, use log level 0.
minimumTriggerIntervalInSeconds integer The minimum time interval in seconds between triggers. Defaults to 30 seconds.
enableAutomaticLocationCollection boolean Whether automatic location collection is enabled (if the user permits).
enableGeofence boolean Whether geofences are enabled.
enableAutomaticGeofenceRequests boolean Whether geofence requests should be made automatically.
dismissModalOnOutsideTap boolean iOS only. Whether a modal in-app message will be dismissed when the user clicks outside of the in-app message.
androidHandlePushDeepLinksAutomatically boolean Android only. Whether the Braze SDK should automatically handle push deep links.
androidPushNotificationHtmlRenderingEnabled boolean Android only. Sets whether the text content in a push notification should be interpreted and rendered as Html using android.text.Html.fromHtml.
androidNotificationAccentColor string Android only. Sets the Android notification accent color.
androidNotificationLargeIcon string Android only. Sets the Android notification large icon.
androidNotificationSmallIcon string Android only. Sets the Android notification small icon.

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

{
  "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",
        }
      ],
    ]
  }
}

Step 2.3: Build and run your application

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

1

expo prebuild

Run your application as specified in the Expo docs. Note that making any changes to the configuration options will require you to prebuild and run the application again.

Step 2.1a: 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.1b: 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.1c: 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.1d: 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.1b: 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

cd ios && pod install

Step 2.2b: 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
) -> Bool {
    // Setup Braze bridge
    let jsCodeLocation : URL = RCTBundleURLProvider.sharedSettings().jsBundleURL(
      forBundleRoot: "index"
    )
    let rootView = RCTRootView(
      bundleURL: jsCodeLocation,
      moduleName: "<YOUR_PROJECT_NAME>",
      initialProperties: nil,
      launchOptions: launchOptions
    )

    // Configure views in the application
    window = UIWindow(frame: UIScreen.main.bounds)
    let rootViewController = UIViewController()
    rootViewController.view = rootView
    window?.rootViewController = rootViewController
    window?.makeKeyAndVisible()

    // 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Setup Braze bridge
  NSURL *jsCodeLocation =
      [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
  RCTRootView *rootView = [[RCTRootView alloc] initWithBundleURL:jsCodeLocation
                                                      moduleName:@"<YOUR_PROJECT_NAME>"
                                               initialProperties:nil
                                                   launchOptions:launchOptions];

  // Configure views in the application
  self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
  UIViewController *rootViewController = [UIViewController new];
  rootViewController.view = rootView;
  self.window.rootViewController = rootViewController;
  [self.window makeKeyAndVisible];

  // 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: Usage

Once installed, you can import the library in your React Native code:

1

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

Reference our sample project for more details.

Test your basic integration

At this point, you can verify that the SDK is integrated by checking session statistics in the dashboard. If you run your application on either platform, you should see a new session in dashboard (in the Overview section).

You can start a session for a particular 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>
  )

You can then search for the user with some-user-id in the dashboard under User Search. There, you can verify that session and device data have been logged.

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