Braze Destination

Braze is a customer engagement platform that helps you better understand your customers’ in-app behavior and use the insights to improve your users’ app experience.

Find the open source transformer code for this destination in the GitHub repository.

Setup

1. In your RudderStack dashboard, go to Directory > Destinations > Cloud Destinations and search for Braze.
2. Connect your source and click Continue.

Connection settings

Configure the following settings to set up Braze as a destination in RudderStack:

• Name: Assign a name to uniquely identify the destination.
• App Key: Enter your Braze app key. For more information on obtaining your Braze app key, see FAQ.
• REST API Key: Enter the REST API key associated with your project. For more information on obtaining this key, see FAQ.

When creating a new Braze Rest API Key for your app, select the following permissions in the User Data section:

• users.track: For creating/updating users and registering events.
• users.identify: For identity resolution of identified and anonymous users.
• users.delete: For deleting users in Braze.
• users.alias.new and users.merge: For aliasing users.
• users.export.ids: For deduplication.

• Data Center: Specify the data center associated with your Braze account. To get your data center details, log in to your Braze account and note your URL. Some examples of identifying the Braze instance from the URL are shown:

Connection compatibility

Destination info
Status: Generally Available Supported sources: Android, iOS , Web, Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify Refer to it as BRAZE in the Integrations object.

Connection modes
Source	Cloud mode	Device mode	Hybrid mode
AMP
Android
Cloud
Cordova
Flutter
iOS
React Native
Shopify
Unity
Warehouse
Web

Supported message types
Source	Identify	Page	Track	Screen	Group	Alias
Cloud mode
Supported sources
Device mode
Android
Flutter
iOS
React Native
Web

Note that:

• This destination supports hybrid mode for the web, iOS and Android sources. For more information, see Send events in hybrid mode section.
• In the web device mode integration, that is, when using JavaScript SDK as a source, RudderStack loads the Braze native SDK from the the https://js.appboycdn.com/ domain. Based on your website’s content security policy, you might need to allowlist this domain to load the Braze SDK successfully.

Send events in hybrid mode

You can use hybrid mode to send all events to Braze from your web, iOS and Android sources.

Mobile sources

To send events via hybrid mode, use the hybrid mode option (highlighted below) while connecting your mobile source to the Braze destination. Then, add the Braze integration to your project.

Web (JavaScript) source

To send events via hybrid mode, use the hybrid mode option (highlighted below) while connecting your web source to the Braze destination.

Then, configure the Web SDK settings to correctly receive data in Braze.

Why use hybrid mode

Certain Braze functionalities like push notifications and in-app messaging require you to load the Braze SDK.

When you choose hybrid mode to send events to Braze, RudderStack:

• Initializes the Braze SDK.
• Sends all the user-generated events (identify, track, page, screen, and group) to Braze only through cloud mode and blocks them from being sent via device mode.
• Sends the auto-generated events (in-app messages, push notifications that require the Braze SDK) via device mode.

With hybrid mode, you can send the auto-generated and user-generated events to Braze using a single connection.

• In hybrid mode, RudderStack sends all the user-generated events to Braze through their REST API and does not process them on the client-side - making your app lean and improving load time.
• You can leverage all the cloud mode benefits like data governance and tracking plans.

Configuration settings

After completing the initial setup, configure the following settings to correctly receive your data in Braze:

• Enable subscription groups in group call: Turn on this setting to send the subscription group status in your group events. For more information, see Group.
• Use Custom Attributes Operation: Turn on this setting if you want to use Braze’s nested custom attributes functionality to create segments and personalize your messages using a custom attribute object. For more information, see Send user traits as nested custom attributes.
• Track events for anonymous users: Turn on this setting to track anonymous user activity and send this information to Braze.

Deduplication settings

• Deduplicate Traits: Turn on this setting to enable traits deduplication for identify and track calls. See Braze Deduplication guide for more information on this feature.

Web SDK settings

• Show Braze logs: Turn on this setting to show Braze logs to the customers.
• Use web push notifications: Turn on this setting to use push notifications for web.

Note that this feature requires you to set up a service worker on your site.

• If your site already registers a service worker, add the following snippet to the service worker file:

self.importScripts("https://js.appboycdn.com/web-sdk/5.0/service-worker.js");

• If you do not have a service worker, create a new file named service-worker.js with the above snippet and place it in the root directory of your website.

• Enable HTML in-app messages: Turn on this setting to enable HTML in-app messages.

Device mode settings

The following settings are applicable only if you’re sending events to Braze via the device mode:

• Client-side Events Filtering: This setting lets you specify which events should be blocked or allowed to flow through to Braze. For more information on this setting, see Client-side Events Filtering.
• Show Braze logs: This setting is applicable only while using the JavaScript SDK as a source. Turn it on to show the Braze logs to your users.
• Consent management provider: Configure the consent management settings for the specified source by choosing the consent management provider from the dropdown. If you choose Custom, make sure to pass the custom consent data to SDK.

Add Braze integration to your project

Depending on your integration platform, follow these steps to add the Braze integration to your project:

pod 'Rudder-Braze'

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

pod 'RudderBraze', '~> 1.0.0'

import RudderBraze

@import RudderBraze;

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

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

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

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

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

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

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

rudder_integration_braze_flutter: ^1.0.1

flutter pub get

import 'package:rudder_integration_braze_flutter/rudder_integration_braze_flutter.dart';

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 following 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"
});

Deleting a user

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

To delete a user, make sure to:

• Configure the REST API key with the users.delete permission.
• Specify the userId in the event. Additionally, you can include a custom identifier (optional) in the event.

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

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

Delta management for identify calls

If you are sending events to Braze via 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.

It is highly recommended to review Braze’s data points policy to fully understand how this functionality can help you avoid data overages.

Track

This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

The track call lets you record the customer events, that is, the actions that they perform, along with any properties associated with them.

A sample track call is shown below:

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

Order Completed

When you call the track method 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 below:

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

Page

The page call allows you to record your website’s page views, with the additional relevant information about the viewed page.

A sample page call is as shown below:

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

Screen

The screen call lets you record your users’ mobile screen views with any additional information about the viewed scren.

A sample screen call is shown below:

[[RSClient sharedInstance] screen:@"Main"
                properties:@{@"prop_key" : @"prop_value"}];

Group

You can use the group call to link an identified user with a group, such as a company, organization, or an account.

RudderStack does not support sending group events to Braze in the device mode.

rudderanalytics.group("12345", {
  name: "MyGroup",
  industry: "IT",
  employees: 450,
  plan: "basic"
});

Once you send a group event, RudderStack sends a custom attribute to Braze with the name as ab_rudder_group_<groupId> and the value as true. For example, if the groupId is 123456, then RudderStack creates a custom attribute with the name ab_rudder_group_123456 and sends it to Braze with its value to true.

Subscription group status

To update the subscription group status, enable the Enable subscription groups in group call setting in the RudderStack dashboard and send the subscription group status in the group call:

rudderanalytics.group("12345", {
  subscriptionState: "subscribed",
  email: "alex@example.com"
});

Either the email or phone is mandatory to send the subscription group in a group call.

Alias

The alias call lets you merge different identities of a known user.

RudderStack supports the alias call for Braze only in cloud mode.

A sample alias call is shown below:

rudderanalytics.alias("user123", "previous123");

When you make the above call, RudderStack removes the user having previousId as previous123 from Braze and merges all the associated fields with the user having userId as user123.

Advanced features

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

Send user traits as nested custom attributes

This feature is available only in cloud mode.

You can send the user traits to Braze as nested custom attributes and perform add, update, and remove operations on them. To do so, enable the Use Custom Attributes Operation dashboard setting in RudderStack while configuring the Braze destination.

You can send the user traits as nested custom attributes in your identify events in the following format:

rudderanalytics.identify("1hKOmRA4GRlm", {
  cars: {
    add: [
      {
        age: 27,
        id: 1,
        name: "Alex Keener"
      }
    ],
    update: [
      {
        age: 30,
        id: 2,
        identifier: "id",
        name: "Rowan"
      },
      {
        age: 27,
        id: 1,
        identifier: "id",
        name: "Mike"
      }
    ]
  },
  country: "USA",
  email: "alex@example.com",
  firstName: "Alex",
  gender: "M",
  pets: [
    {
      breed: "beagle",
      id: 1,
      name: "Scooby",
      type: "dog"
    },
    {
      breed: "calico",
      id: 2,
      name: "Garfield",
      type: "cat"
    }
  ]
});

To send the user traits as custom user attributes via the track, page, or screen calls, pass traits as a contextual field in the event.

rudderanalytics.track(
  "Product Viewed",
  {
    revenue: 8.99,
    currency: "USD"
  },
  {
    traits: {
      cars: {
        add: [
          {
            age: 27,
            id: 1,
            name: "Alex Keener"
          }
        ],
        update: [
          {
            age: 30,
            id: 2,
            identifier: "id",
            name: "Mike"
          },
          {
            age: 27,
            id: 1,
            identifier: "id",
            name: "Rowan"
          }
        ]
      },
      city: "Disney",
      country: "USA",
      email: "alexa@example.com",
      firstName: "Alexa",
      gender: "woman",
      pets: [
        {
          breed: "beagle",
          id: 1,
          name: "Scooby",
          type: "dog"
        },
        {
          breed: "calico",
          id: 2,
          name: "Garfield",
          type: "cat"
        }
      ]
    }
  }
);

Note that:

• For the update and remove operations, identifier is a required key.
• If add, update, or remove operations are not present in the nested array, RudderStack uses the create operation to create the properties, by default.

For more information on sending nested custom attributes to Braze, see the Braze documentation.

Send push notification events

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

[[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);
}];

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

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

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.

To send in-app message events to Braze:

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

pod 'BrazeUI'

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

@import BrazeUI;

4. 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;

5. 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.")
    }
}

6. 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
}

FAQ

Where can I find the Braze App Key and REST API Key?

1. Log in to your Braze dashboard.
2. Go to Settings > API Keys.

You can find the REST API key for your workspace under the REST API Keys section:

You can find your Braze App Key in the Identification section:

Questions? Contact us by email or on Slack