Braze Device Mode Integration

Send events to Braze in RudderStack device mode.

10 minute read

After you have successfully instrumented Braze as a destination in RudderStack, follow this guide to correctly send your events to Braze in device mode.

Add Braze integration

Make sure to add the Braze integration to your project before sending events to Braze in device mode.

Depending on your integration platform, follow these steps:

Open the Podfile of your project and add the following:

pod 'Rudder-Braze'

Run the pod install command.
Change the SDK initialization to the following snippet:

RudderConfigBuilder *builder = [[RudderConfigBuilder alloc] init];
[builder withDataPlaneUrl:<data_plane_url>];
[builder withFactory:[RudderBrazeFactory instance]];
[RudderClient getInstance:<write_key>; config:[builder build]];

RudderStack supports this device mode integration for Braze v4.4.4 and above.

Install RudderBraze (available through CocoaPods) by adding the following to your Podfile:

pod 'RudderBraze', '~> 1.0.0'

Run the pod install command.
Import the SDK depending on your preferred platform:

import RudderBraze

@import RudderBraze;

Add the imports to your AppDelegate file under the didFinishLaunchingWithOptions method:

let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)
RSClient.sharedInstance().configure(with: config)
RSClient.sharedInstance().addDestination(RudderBrazeDestination())

RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];
[[RSClient sharedInstance] configureWith:config];
[[RSClient sharedInstance] addDestination:[[RudderBrazeDestination alloc] init]];

To send push notification events, see Send push notifications.

The Braze integration v1.0.0 and above requires minimum SDK version (minSdk) of 25.

Follow the steps in this section to add Braze to your Kotlin project.

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle), add the following dependencies for the RudderStack-Braze integration:

dependencies {
  // ...
  
  // Add Rudder Kotlin and Braze integration SDKs:
  implementation("com.rudderstack.sdk.kotlin:android:<latest-version>")
  implementation("com.rudderstack.integration.kotlin:braze:<latest-version>")
}

For further steps on permissions and other optional configurations, see the Braze documentation.
Add the SDK initialization and the Rudder-Braze integration in your Application class:

import android.app.Application
import com.rudderstack.sdk.kotlin.android.Analytics
import com.rudderstack.sdk.kotlin.android.Configuration
import com.rudderstack.integration.kotlin.braze.BrazeIntegration

class MyApplication : Application() {
    lateinit var analytics: Analytics

    override fun onCreate() {
        super.onCreate()
        analytics = Analytics(
            configuration = Configuration(
                writeKey = "WRITE_KEY",
                application = this,
                dataPlaneUrl = "DATA_PLANE_URL",
            )
        )
        
        analytics.add(BrazeIntegration())
    }
}

Add the following under dependencies section:

implementation 'com.rudderstack.android.sdk:core:[1.0,2.0)'
implementation 'com.rudderstack.android.integration:braze:[1.3.0,)'

The Braze-RudderStack Android SDK integration v2.0.0 and above requires a minimum SDK version (minSdkVersion) of 25.

Add the following permissions to the AndroidManifest.xml file:

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

Change the SDK initialization to the following:

// initialize Rudder SDK
val rudderClient: RudderClient =
    RudderClient.getInstance(
        this,
        WRITE_KEY,
        RudderConfig.Builder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
            .withFactory(BrazeIntegrationFactory.FACTORY)
            .build()
    )

Important
The React Native-Braze integration has a known limitation.
See the React Native and Flutter limitation section for more details and workaround on this limitation.

Add the RudderStack-Braze module to your app by running the following command:

npm install @rudderstack/rudder-integration-braze-react-native

yarn add @rudderstack/rudder-integration-braze-react-native

Import the module you added above and add it to your SDK initialization code:

import rudderClient from "@rudderstack/rudder-sdk-react-native";
import braze from "@rudderstack/rudder-integration-braze-react-native";
const config = {
  dataPlaneUrl: DATA_PLANE_URL,
  trackAppLifecycleEvents: true,
  withFactories: [braze]
};
rudderClient.setup(WRITE_KEY, config);

Important
The Flutter-Braze integration has a known limitation.
See the React Native and Flutter limitation section for more details and workaround on this limitation.

Add the following dependency to the dependencies section of your pubspec.yaml file:

rudder_integration_braze_flutter: ^1.0.1

Run the below command to install the dependency added in the above step:

flutter pub get

Import the RudderIntegrationBrazeFlutter in your application where you are initializing the SDK:

import 'package:rudder_integration_braze_flutter/rudder_integration_braze_flutter.dart';

Change the initialization of your RudderClient as shown:

final RudderController rudderClient = RudderController.instance;
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withFactory(RudderIntegrationBrazeFlutter());
rudderClient.initialize(<write_key>, config: builder.build(), options: null);

Limitations for React Native and Flutter

Braze requires different App Keys for Android and iOS platforms. Currently, there is no way to provide App Keys per platform when using the React Native or Flutter SDKs with the Braze integration. This is a known limitation — the RudderStack team has a planned item to fix it in the near future.

You can work around this limitation by creating separate integrations and sources for Android and iOS. See the below sections for detailed steps.

Step 1: Create separate integrations

Create two Braze destination integrations in the RudderStack dashboard:

Braze Android: Configure this integration with your Android App Key.
Braze iOS: Configure this integration with your iOS App Key.

Step 2: Create separate sources

Create two sources in the RudderStack dashboard:

Flutter / React Native Android
Flutter / React Native iOS

Step 3: Connect sources to destinations

Connect the Flutter Android source to the Braze Android destination.
Connect the Flutter iOS source to the Braze iOS destination.

Step 4: Platform-specific SDK initialization

During SDK initialization, use platform checks to conditionally initialize the appropriate RudderStack SDK.

The example code snippets for Flutter and React Native are shown below:

import 'dart:io';
import 'package:rudder_sdk_flutter_platform_interface/platform.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';
import 'package:rudder_integration_braze_flutter/rudder_integration_braze_flutter.dart';

void initializeRudderSDK() {
    String writeKey = "";
    if (Platform.isAndroid) {
      writeKey = "<FLUTTER_ANDROID_WRITE_KEY>";
    } else if (Platform.isIOS) {
      writeKey = "<FLUTTER_IOS_WRITE_KEY>";
    }

    final RudderController rudderClient = RudderController.instance;
    RudderConfigBuilder builder = RudderConfigBuilder();
    builder
      ..withFactory(RudderIntegrationBrazeFlutter())
      ..withDataPlaneUrl(<DATA_PLANE_URL>)
    rudderClient.initialize(writeKey, config: builder.build());
}

Replace FLUTTER_ANDROID_WRITE_KEY and FLUTTER_IOS_WRITE_KEY with the actual write keys from your respective Flutter sources (for Android and iOS) created in Step 2.

import { Platform } from 'react-native';
import rudderClient from "@rudderstack/rudder-sdk-react-native";
import braze from "@rudderstack/rudder-integration-braze-react-native";

const rudderInitialise = async () => {
  let writeKey = '';
  if (Platform.OS === 'android') {
    writeKey = '<REACT_NATIVE_ANDROID_WRITE_KEY>';
  } else if (Platform.OS === 'ios') {
    writeKey = '<REACT_NATIVE_IOS_WRITE_KEY>';
  }

  await rudderClient.setup(writeKey, {
    dataPlaneUrl: DATA_PLANE_URL,
    withFactories: [braze]
  });
};

rudderInitialise().catch(console.error);

Replace REACT_NATIVE_ANDROID_WRITE_KEY and REACT_NATIVE_IOS_WRITE_KEY with the actual write keys from your respective React Native sources (for Android and iOS) created in Step 2.

Identify

You can use the identify call to identify a user in Braze in any of the below cases:

When the user registers to the app for the first time.
When they log into their app.
When they update their information.

A sample identify call is shown below:

rudderanalytics.identify("1hKOmRA4GRlm", {
  email: "alex@example.com",
  name: "Alex Keener"
});

Set custom user ID (`externalId`)

In mobile device mode, that is, when using Android, iOS, React Native, or Flutter as source, you need to pass externalId in your identify events. Otherwise, Braze uses userId to identify the user.

Braze gives first preference to the externalId field in the identify event to identify the user. If externalId is absent, it falls back to the userId field.

The following code snippet shows how to add an externalId to your identify event using the React Native SDK:

const options = {
  externalIds: [
    {
      id: "<your_external_id>",
      type: "brazeExternalId",
    },
  ],
}
rudderClient.identify(
  "1hKOmRA4GRlm",
  {
    email: "alex@example.com",
    gender: "male",
  },
  options
)

Make sure to send the identify event containing the externalId before sending any subsequent track events. That way, RudderStack is able to successfully persist the externalId information in all the future events.

Track

The track event lets you record the customer events along with any associated properties.

A sample track call is shown below:

rudderanalytics.track("Product Added", {
  numberOfRatings: "12",
  name: "item 1"
});

Order Completed

When you use the track call for an Order Completed event, RudderStack sends the product information present in the event to Braze as purchases.

A sample Order Completed event is shown:

rudderanalytics.track("Order Completed", {
  userId: "1hKOmRA4GRlm",
  currency: "USD",
  products: [
    {
      product_id: "123454387",
      name: "Game",
      price: 15.99
    }
  ]
});

Page

The page event lets you record your website’s page views, with the additional relevant information about the viewed page.

A sample page call is as shown:

rudderanalytics.page("Cart", "Cart Viewed", {
  path: "/cart",
  referrer: "test.com",
  search: "term",
  title: "test_item",
  url: "http://test.in"
});

Delta management for `identify` and `track` calls

If you are sending events to Braze in device mode, you can save costs by deduplicating your identify calls. To do so, enable the Deduplicate Traits dashboard setting. RudderStack then sends only the changed or modified attributes (traits) to Braze.

RudderStack recommends reviewing Braze’s data points policy to fully understand how this functionality can help you avoid data overages.

Advanced features

This section covers some advanced Braze operations that you can perform using RudderStack.

Send push notification events

Depending on your iOS SDK version, follow these steps to send push notification events to Braze:

Follow the Braze documentation to generate a push notification certificate.
Add the following code to your AppDelegate file under the didFinishLaunchingWithOptions method:

[[UIApplication sharedApplication] registerForRemoteNotifications];

UNUserNotificationCenter *center = UNUserNotificationCenter.currentNotificationCenter;
[center setNotificationCategories:BRZNotifications.categories];
center.delegate = self;
UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
if (@available(iOS 12.0, *)) {
    options = options | UNAuthorizationOptionProvisional;
}
[center requestAuthorizationWithOptions:options
                      completionHandler:^(BOOL granted, NSError *_Nullable error) {
    NSLog(@"Notification authorization, granted: %d, "
          @"error: %@)",
          granted, error);
}];

You must assign the delegate object using center.delegate = self synchronously before your app finishes launching - preferably in application:didFinishLaunchingWithOptions.
Otherwise, your app may miss any incoming push notificaitons. See Apple’s UNUserNotificationCenterDelegate documentation for more information.

// - Register the device token with Braze
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    if ([RudderBrazeFactory instance].integration) {
        [[RudderBrazeFactory instance].integration didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
}

Make sure that RudderBrazeFactory is initialized before making calls to this push API.
Since the Braze push API is designed as an instance method, it relies on the SDK that is correctly initialized beforehand. To do this, you can utilize the dispatch_after API.

Enable push handling:

// - Add support for silent notification

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler: (void (^)(UIBackgroundFetchResult))completionHandler {
    if ([RudderBrazeFactory instance].integration) {
        [[RudderBrazeFactory instance].integration didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    }
}

// - Add support for push notifications

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler {
    if ([RudderBrazeFactory instance].integration) {
        [[RudderBrazeFactory instance].integration didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
    }
}

// - Add support for displaying push notification when the app is currently running in the foreground

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler: (void (^)(UNNotificationPresentationOptions))completionHandler {
    if (@available(iOS 14, *)) {
        completionHandler(UNNotificationPresentationOptionList |
                          UNNotificationPresentationOptionBanner);
    } else {
        completionHandler(UNNotificationPresentationOptionAlert);
    }
}

Braze recommends invoking the push integration code within the application’s main thread.

Add the following code to your AppDelegate file under the didFinishLaunchingWithOptions method:

if #available(iOS 10, *) {
    let center = UNUserNotificationCenter.current()
    center.delegate = self
    var options: UNAuthorizationOptions = [.alert, .sound, .badge]
    if #available(iOS 12.0, *) {
        options = UNAuthorizationOptions(rawValue: options.rawValue | UNAuthorizationOptions.provisional.rawValue)
        }
        center.requestAuthorization(options: options) { (granted, error) in
            RSClient.sharedInstance().pushAuthorizationFromUserNotificationCenter(granted)
    }
    UIApplication.shared.registerForRemoteNotifications()
} else {
    let types: UIUserNotificationType = [.alert, .badge, .sound]
    let setting: UIUserNotificationSettings = UIUserNotificationSettings(types: types, categories: nil)
    UIApplication.shared.registerUserNotificationSettings(setting)
    UIApplication.shared.registerForRemoteNotifications()
}

if (floor(NSFoundationVersionNumber) > NSFoundationVersionNumber_iOS_9_x_Max) {
  UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
  center.delegate = self;
  UNAuthorizationOptions options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
  if (@available(iOS 12.0, *)) {
  options = options | UNAuthorizationOptionProvisional;
  }
  [center requestAuthorizationWithOptions:options
                        completionHandler:^(BOOL granted, NSError * _Nullable error) {
      [[RSClient sharedInstance] pushAuthorizationFromUserNotificationCenter:granted];
  }];
  [[UIApplication sharedApplication] registerForRemoteNotifications];
} else {
  UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:(UIUserNotificationTypeBadge | UIUserNotificationTypeAlert | UIUserNotificationTypeSound) categories:nil];
  [[UIApplication sharedApplication] registerForRemoteNotifications];
  [[UIApplication sharedApplication] registerUserNotificationSettings:settings];
}

Send in-app message events

This feature is available in the iOS SDK v1 device mode integration starting from version 1.4.0.

Add the following line to your Podfile for Braze IAM support:

pod 'BrazeUI'

Navigate to your Xcode app project directory and run pod install.
Import the BrazeUI SDK in your AppDelegate.m file:

@import BrazeUI;

Add a static variable to your AppDelegate.m file to keep a reference to the Braze instance throughout your app’s lifetime:

static Braze *braze;

Add the following code in your AppDelegate.m file just after the RudderStack iOS SDK initialization snippet:

id<RSIntegrationFactory> brazeFactoryInstance = [RudderBrazeFactory instance];
// RudderStack SDK initialization
[[RSClient getInstance] onIntegrationReady:brazeFactoryInstance withCallback:^(NSObject *brazeInstance) {
    if (brazeInstance && [brazeInstance isKindOfClass:[Braze class]]) {
        braze = (Braze *)brazeInstance;
        [self configureIAM];
    } else {
        NSLog(@"Error getting Braze instance.");
    }
}];

let brazeFactoryInstance = RudderBrazeFactory()
// RudderStack SDK initialization
RSClient.getInstance().onIntegrationReady(brazeFactoryInstance) { brazeInstance in
    if let brazeInstance = brazeInstance as? Braze {
        AppDelegate.braze = brazeInstance
        self.configureIAM()
    } else {
        print("Error getting Braze instance.")
    }
}

Add the configureIAM method in the AppDelegate.m file:

-(void) configureIAM {
    // Refer here: https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/in-app_messaging/customization/setting_delegates/#setting-the-in-app-message-delegate
    BrazeInAppMessageUI *inAppMessageUI = [[BrazeInAppMessageUI alloc] init];
    braze.inAppMessagePresenter = inAppMessageUI;
}

func configureIAM() {
    // Refer here: https://www.braze.com/docs/developer_guide/platform_integration_guides/swift/in-app_messaging/customization/setting_delegates/#setting-the-in-app-message-delegate
    let inAppMessageUI: BrazeInAppMessageUI = BrazeInAppMessageUI()
    AppDelegate.braze?.inAppMessagePresenter = inAppMessageUI
}

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by Email or on Slack