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:
Our example uses the bundleURL
parameter to initialize the RCTRootView
object, but note that your project is not strictly tied to this initialization method and may use other initializers such as the initWithBridge
method instead.
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:
Our example uses the bundleURL
parameter to initialize the RCTRootView
object, but note that your project is not strictly tied to this initialization method and may use other initializers such as the initWithBridge
method instead.
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.