Braze Destination

Send your event data from RudderStack to Braze.

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

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:
URLData center instance
https://dashboard-01.braze.comUS-01
https://dashboard-03.braze.comUS-03
https://dashboard-01.braze.euEU-01

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
SourceCloud modeDevice modeHybrid mode
AMPsupportednot supportednot supported
Androidsupportedsupportedsupported
Cloudsupportednot supportednot supported
Cordovasupportednot supportednot supported
Fluttersupportedsupportednot supported
iOSsupportedsupportedsupported
React Nativesupportedsupportednot supported
Shopifysupportednot supportednot supported
Unitysupportednot supportednot supported
Warehousesupportednot supportednot supported
Websupportedsupportedsupported
Supported message types
SourceIdentifyPageTrackScreenGroupAlias
Cloud mode
Supported sourcessupportedsupportedsupportedsupportedsupportedsupported
Device mode
Androidsupportednot supportedsupportednot supportednot supportednot supported
Fluttersupportednot supportedsupportednot supportednot supportednot supported
iOSsupportednot supportedsupportednot supportednot supportednot supported
React Nativesupportednot supportedsupportednot supportednot supportednot supported
Websupportedsupportedsupportednot supportednot supportednot supported
info

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.

Braze hybrid mode connection setting

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.

Braze hybrid mode connection setting for web

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

Why use hybrid mode

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

success
  • 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.
info

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:

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.

info

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

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

warning
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"
});
info
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.

warning
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

info
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"
        }
      ]
    }
  }
);
warning

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:

Send in-app message events

info
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'
  1. Navigate to your Xcode app project directory and run pod install.
  2. Import the BrazeUI SDK in your AppDelegate.m file:
@import BrazeUI;
  1. 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;
  1. Add the following code in your AppDelegate.m file just after the RudderStack iOS SDK initialization snippet:
  1. Add the configureIAM method in the AppDelegate.m file:

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:

Braze REST API Key

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

Braze App Key

Questions? Contact us by email or on Slack