Skip to content

Segment

Segment is a customer data platform that helps you collect, clean, and activate your customer data.

The Braze and Segment integration allows you to track your users and route data to various user analytics providers. Segment allows you to:

Prerequisites

Integration

To integrate Braze and Segment, you must set Braze as a destination in accordance with your chosen integration type (connection mode). If you’re a new-to-Braze customer, you can relay historical data to Braze using Segment replays. Next, you must set up mappings and test your integration to ensure smooth data flow between Braze and Segment.

Step 1: Create a Braze destination

After successfully setting up your sources, you’ll need to configure Braze as a destination for each source (iOS, Android, web, etc.). You’ll have many options to customize the data flow between Braze and Segment using the connection settings.

Step 2: Choose destination framework and connection type

In Segment, navigate to Destinations > Braze > Configure Braze > Select your Source > Setup.

The source setup page. This page includes settings to set the destination framework as either "actions" or "classic" and set the connection mode as either "cloud mode" or "device mode".

You can integrate Segment’s web source (Analytics.js) and native client-side libraries with Braze using either a side-by-side (device-mode) integration or a server-to-server (cloud-mode) integration.

Your choice of connection mode will be determined by the type of Source the destination is configured for.

Side-by-side SDK integration

Also called device-mode, this integration maps Segment’s SDK and methods to the Braze SDK, allowing access to all the features our SDK provides, such as push, in-app messaging, and other methods native to Braze.

When using a device-mode connection, similar to integrating the Braze SDK natively, the Braze SDK will assign a device_id and a backend identifier, braze_id, to every user. This allows Braze to capture anonymous activity from the device by matching those identifiers instead of userId.

To set up Braze as a device-mode destination for your Android source, choose Actions as the Destination framework, then select Save.

To complete the side-by-side integration, refer to Segment’s detailed instructions for adding the Braze destination dependency to your Android app.

The source code for the Android device mode integration is maintained by Braze and is updated regularly to reflect new Braze SDK releases.

To set up Braze as a device-mode destination for your iOS source, choose Actions as the Destination framework, then select Save.

To complete the side-by-side integration, refer to Segment’s detailed instructions for adding the Braze Segment pod to your iOS app.

The source code for the iOS device mode integration is maintained by Braze and is updated regularly to reflect new Braze SDK releases.

Segment’s Braze Web Mode (Actions) framework is recommended for setting up Braze as a device-mode destination for your web source.

In Segment, select Actions as your destination framework and Device Mode as your connection mode.

The source code for the React Native Braze plugin is maintained by Segment and is updated regularly to reflect new Braze SDK releases.

When connecting a React Native Segment Source to Braze, you must set up a source and destination per operating system. For example, setting up an iOS destination and an Android destination.

Within your app codebase, conditionally initialize the Segment SDK by device type, using the respective source write key associated with each app.

When a push token is registered from a device and sent to Braze, it is associated with the app identifier used when initializing the SDK. The device-type conditional initialization helps confirm that any push tokens sent to Braze are associated with the relevant app.

To set up Braze as a device-mode destination for each source, choose Actions as the Destination framework, then select Save.

Server-to-server integration

Also called cloud-mode, this integration forwards data from Segment to Braze’s REST APIs. Use Segment’s Braze Cloud Mode (Actions) framework to set up a cloud-mode destination for any of your sources.

Unlike the side-by-side integration, the server-to-server integration does not support Braze’s UI features, such as in-app messaging, Content Cards, or automatic push token registration. There also exists automatically captured data (such as anonymous users and device-level fields) that are not available through cloud-mode.

If you wish to use this data and these features, consider using the side-by-side (device-mode) SDK integration.

The source code for the Braze Cloud Mode (Actions) destination is maintained by Segment.

Step 3: Settings

Define the settings for your destination. Not at all settings will apply to all destination types.

Step 4: Map methods

Braze supports the Page, Identify, and Track Segment methods. The types of identifiers used within these methods will depend on whether the data is being sent through a server-to-server (cloud-mode) or side-by-side (device-mode) integration. In the Braze Web Mode Actions and Cloud Mode Actions destinations, you can also choose to set up a mapping for a Segment alias call.

The Cloud Mode (Actions) Destination offers a Create Alias action that can be used to create an alias-only user or add an alias to an existing external_id profile. The Identify User action can be used alongside the Create Alias action to merge an alias-only user with an external_id after one becomes available for the user.

It is also possible to engineer a workaround and use braze_id to send anonymous user data in cloud-mode. This requires manually including the user’s braze_id in all your Segment API calls. You can learn more about how to set up this workaround in Segment’s documentation.

Destinations data sent to Braze can be batched within Cloud Mode Actions. Batch sizes are capped at 75 events, and these batches will accumulate over a 30-second period before being flushed. Request batching is done per-action. For example, Identify Calls (attributes) will be batched in a request and Track Calls (custom events) will be batched in a second request. Braze recommends enabling this feature as it will reduce the number of requests being sent from Segment to Braze. In turn, this will reduce the risk of the destination hitting Braze rate limits and retrying requests.

You can turn on batching for an action by navigating to your Braze Destination > Mappings. From there, click the 3-dot icon to the right of the mapping and select Edit Mapping. Scroll to the bottom of the Select mappings section and make sure that Batch Data to Braze is set to Yes.

Identify

The Identify call lets you tie a user to their actions and record attributes about them.

Certain Segment special traits map to standard attribute profile fields in Braze:

Other reserved Braze profile fields such as email_subscribe and push_subscribe can be sent by using the Braze naming convention for these fields and passing them as traits within an identify call.

Adding a user to a subscription group

You can also subscribe or unsubscribe a user from a given subscription group using the following fields in the traits parameter.

Use the reserved Braze profile field called braze_subscription_groups, which can be associated with an array of objects. Each object in the array should have two reserved keys:

  1. subscription_group_state: Indicates whether the user is "subscribed" or "unsubscribed" to a specific subscription group.
  2. subscription_group_id: Represents the unique ID of the subscription group. You can find this ID in the Braze dashboard under Subscription Group Management.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
analytics.identify(
  userId: "{your-user}",
  traits: [
    "braze_subscription_groups": [
      [
        "subscription_group_id": "{your-group-id}",
        "subscription_group_state": "subscribed"
      ],
      [
        "subscription_group_id", "{your-group-id}",
        "subscription_group_state": "unsubscribed"
      ]
    ]
  ]
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
analytics.identify(
  "{your-user}",
  buildJsonObject {
    put("braze_subscription_groups", buildJsonArray {
        add(
          buildJsonObject {
            put("subscription_group_id", "{your-group-id}")
            put("subscription_group_state", "subscribed")
          }
        )
        add(
          buildJsonObject {
            put("subscription_group_id", "{your-group-id}")
            put("subscription_group_state", "unsubscribed")
          }
        )
      }
    )
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
analytics.identify(
  "{your-user}",
  {
    braze_subscription_groups: [
      {
        subscription_group_id: "{your-group-id}",
        subscription_group_state: "subscribed"
      },
      {
        subscription_group_id: "{your-group-id}",
        subscription_group_state: "unsubscribed"
      }
    ]
  }
)
Custom attributes

All other traits will be recorded as custom attributes.

In the Web Mode Actions and Cloud Mode Actions destinations, the above mappings can be set using the Update User Profile Action.

Track

When you track an event, we will record that event as a custom event using the name provided.

Metadata sent within the properties object of the track call will be logged in Braze as the custom event properties for the associated event. All custom event property data types are supported.

In the Web Mode Actions and Cloud Mode Actions destinations, the above mappings can be set using the Track Event Action.

Order completed

When you track an event with the name Order Completed using the format described in Segment’s eCommerce API, we will record the products you’ve listed as purchases.

In the Web Mode Actions and Cloud Mode Actions destinations, the default mapping can be customized through the Track Purchase Action.

Page

The Page call lets you record whenever a user sees a page of your website, along with any optional properties about the page.

This event type can be used as a trigger in the Web Mode Actions and Cloud Actions destinations to log a custom event to Braze.

Step 5: Test your integration

When using the side-by-side (device-mode) integration, your overview metrics (lifetime sessions, MAU, DAU, stickiness, daily sessions, and daily sessions per MAU) can be used to ensure that Braze is receiving data from Segment.

You can view your data in the custom events or revenue pages, or by creating a segment. The dashboard’s Custom Events page lets you view custom event counts over time. Note that you will not be able to use formulas that include MAU and DAU statistics when using a server-to-server (cloud mode) integration.

If you’re sending purchase data to Braze (see order completed in the Track tab of Step 3), the revenue page allows you to view data on revenue or purchases over specific periods or your app’s total revenue.

Creating a segment allows you to filter your users based on the custom event and attribute data.

User deletion and suppression

If you need to delete or suppress users, note that Segment’s user delete feature is mapped to the Braze /users/delete endpoint. Note that verification of these deletions could take up to 30 days.

You must ensure that you select a common user identifier between Braze and Segment (as in external_id). After you’ve initiated a deletion request with Segment, you can view the status within the deletion requests tab in your Segment dashboard.

Segment replays

Segment provides a service to clients to “replay” all historical data to a new technology partner. New Braze customers who want to import all relevant historical data can do so through Segment. Talk to your Segment rep if this is something you are interested in.

Segment will connect to our /users/track endpoint to import user data into Braze on your behalf.

Best practices

Review use cases to avoid data overages.

Segment does not limit the number of data elements clients send to them. Segment allows you to send all or decide which events you will send to Braze. Rather than sending all of your events using Segment, we suggest you review use cases with your marketing and editorial teams to determine which events you will send to Braze to avoid data overages.

Understand the difference between the custom API endpoint and the custom REST API endpoint in the Mobile Device Mode destination settings.

Your Braze API endpoint (called the “Custom API Endpoint” in Segment) is the SDK endpoint that Braze sets up for your SDK (for example, sdk.iad-03.braze.com). Your Braze REST API endpoint (called the “Custom REST API Endpoint” in Segment) is the REST API endpoint (for example, https://rest.iad-03.braze.com)

Ensure your custom API endpoint is correctly input into the mobile device mode destination settings.

The proper format must be followed to ensure that you input your Braze SDK endpoint correctly. Your Braze SDK endpoint must not include https:// (for example, sdk.iad-03.braze.com), or else the Braze integration will break. This is required because Segment automatically prepends your endpoint with https://, resulting in Braze initializing with an invalid endpoint https://https://sdk.iad-03.braze.com.

Data mapping nuances.

Scenarios where data will not pass as expected:

  1. Nested custom attributes
    • Although nested custom attributes can technically be sent to Braze through Segment, the entire payload will be sent each time. This will incur data points per key passed in the nested object each time the payload is sent.

      To spend only a subset of data points when the payload sends, you can use the custom destination functions feature owned by Segment. This feature in the Segment platform allows you to customize how data is sent to downstream destinations.
  1. Passing anonymous data server-to-server.
    • Customers may use Segment’s server-to-server libraries to funnel anonymous data to other systems. See the map methods section to learn more about sending users without an external_id to Braze via a server-to-server (cloud-mode) integration.
Customization of Braze initialization.

There are several different ways that Braze can be customized: push, in-app messages, Content Cards, and initialization. With a side-by-side integration, you can still customize push, in-app messages, and Content Cards as you would with a direct Braze integration.

However, customizing when the Braze SDK is integrated or specifying initialization configurations may be difficult and sometimes not possible. This is because Segment will initialize the Braze SDK for you when the Segment initialization occurs.

Sending deltas to Braze.

When passing user attribute data, check that you only pass values for attributes that have changed since the last update. This will ensure you do not unnecessarily consume data points toward your allotment. For client-side sources, use Segment’s open-source Middleware tool to optimize your integration and limit Data Point usage by debouncing duplicate identify() calls from Segment.

HOW HELPFUL WAS THIS PAGE?
New Stuff!