Braze Device Mode Integration

Send events to Braze in RudderStack device mode.

8 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.

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,)'

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()
    )

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);

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);

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.

Delete user

You can delete a user in Braze using the Suppression with Delete regulation of the RudderStack User Suppression API.

Note that:
The User Suppression API is available for the RudderStack Cloud Enterprise users only.
To delete a user, you must specify their userId in the event. You can also specify a custom identifier (optional) in the event.

A sample regulation request body for deleting a user in Braze is shown:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": ["2FIKkByqn37FhzczP23eZmURciA"],
  "users": [
    {
      "userId": "1hKOmRA4GRlm",
      "<customKey>": "<customValue>"
    }
  ]
}

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