Customer.io

Braze destination

Web only mode

You can set up this integration in “web” mode. When set up this way, our JavaScript client will load the Braze SDK and send data directly to Braze, bypassing Customer.io entirely.

We don’t typically recommend setting things up this way, because:

  1. You won’t capture data in Customer.io.
  2. As the name suggests, you cannot use this mode with other sources of data (mobile SDKs, server-side libraries, and so on).
  3. It can be hard to debug this sort of implementation.

Otherwise, there are very few functional differences besides the sources they support.

Getting started

  1. Go to Data & Integrations > Integrations and select the Braze entry in the Directory tab.
  2. (Optional) Select the data sources that you want to connect to your outbound integration. You can always connect data sources later. We'll only show you data sources that work with your integration.
  3. Configure your integration.
    1. API Key: Created under Developer Console in the Braze Dashboard.
    2. App ID: The app identifier used to reference specific Apps in requests made to the Braze API. Created under Developer Console in the Braze Dashboard.
    3. REST Endpoint: Your Braze REST endpoint. [See more details](https://www.braze.com/docs/api/basics/#endpoints)
  4. Click Enable Destination.

Identifiers in Braze

Braze calls require an external_id or a braze_id. We map userId from source events to Braze’s external_id. The braze_id is essentially Braze’s anonymous ID.

So, if you haven’t identified a user by userId, we use the braze_id—which is just Braze’s anonymous Identifier. Otherwise, when you’ve identified someone, we’ll use the external_id.

Actions

When you're done setting things up, you can go to the Actions tab to see how we map incoming data to your integration.

You may need to add actions for this integration

While we often have default triggers for actions, we don't always add those actions as defaults. You may need to add actions to make sure that you're sending all the data that you want to send to your integration. See our actions page for help setting up actions.

Update User Profile

Default Trigger:type = "identify"

Update a user's profile attributes in Braze

  • external_idstring
    Default: $.userId
    The unique user identifier
  • user_aliasobject
    A user alias object. See the docs.
  • braze_idstringnull
    Default: $.properties.braze_id
    The unique user identifier
  • countrystringnull
    Default: $.context.location.country
    The country code of the user
  • The user's current longitude/latitude.
  • date_of_first_sessionstringnull(date-time)
    The date the user first used the app
  • date_of_last_sessionstringnull(date-time)
    The date the user last used the app
  • dobstringnull(date-time)
    The user's date of birth
  • emailstringnull
    Default: $.traits.email
    The user's email
  • email_subscribestring
    The user's email subscription preference: “opted_in” (explicitly registered to receive email messages), “unsubscribed” (explicitly opted out of email messages), and “subscribed” (neither opted in nor out).
  • email_open_tracking_disabledboolean
    Set to true to disable the open tracking pixel from being added to all future emails sent to this user.
  • email_click_tracking_disabledboolean
    Set to true to disable the click tracking for all links within a future email, sent to this user.
  • Hash of Facebook attribution containing any of id (string), likes (array of strings), num_friends (integer).
  • first_namestringnull
    Default: $.traits.firstName
    The user's first name
  • genderstringnull
    The user's gender: “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say) or nil (unknown).
    Accepted values: M, F, O, N, P
  • home_citystringnull
    Default: $.traits.address.city
    The user's home city.
  • image_urlstringnull
    Default: $.traits.avatar
    URL of image to be associated with user profile.
  • languagestringnull
    The user's preferred language.
  • last_namestringnull
    Default: $.traits.lastName
    The user's last name
  • marked_email_as_spam_atstringnull(date-time)
    The date the user marked their email as spam.
  • phonestringnull
    Default: $.traits.phone
    The user's phone number
  • push_subscribestring
    The user's push subscription preference: “opted_in” (explicitly registered to receive push messages), “unsubscribed” (explicitly opted out of push messages), and “subscribed” (neither opted in nor out).
  • Array of objects, each containing app_id and token string. You can also provide a device_id for each device. But if you don't provide this field, one will be randomly generated.
  • time_zonestring
    The user’s time zone name from the IANA Time Zone Database (e.g., “America/New_York” or “Eastern Time (US & Canada)”). Only sets valid time zone values.
  • Hash containing any of id (integer), screen_name (string, Twitter handle), followers_count (integer), friends_count (integer), statuses_count (integer).
  • Default: $.traits
    Hash of custom attributes to send to Braze
  • _update_existing_onlyboolean
    Default: false
    Setting this flag to true will put the API in "Update Only" mode. When using a "user_alias", "Update Only" mode is always true.

Track Event

Default Trigger:type = "track" and event != "Order Completed"

Record custom events in Braze

  • external_idstring
    Default: $.userId
    The unique user identifier
  • user_aliasobject
    A user alias object. See the docs.
  • braze_idstringnull
    Default: $.properties.braze_id
    The unique user identifier
  • namestring
    Default: $.event
    The event name
  • timestring(date-time)
    Default: $.receivedAt
    When the event occurred.
  • Default: $.properties
    Properties of the event
  • _update_existing_onlyboolean
    Default: false
    Setting this flag to true will put the API in "Update Only" mode. When using a "user_alias", "Update Only" mode is always true.
  • enable_batchingboolean
    Default: false
    If true, Segment will batch events before sending to Braze’s user track endpoint. Braze accepts batches of up to 75 events.

Track Purchase

Default Trigger:event = "Order Completed"

Record purchases in Braze

  • external_idstring
    Default: $.userId
    The unique user identifier
  • user_aliasobject
    A user alias object. See the docs.
  • braze_idstringnull
    Default: $.properties.braze_id
    The unique user identifier
  • timestring(date-time)
    Default: $.receivedAt
    When the event occurred.
  • Default: $.properties.products
    Any array of objects, where each object represents a product in the purchase
  • Default: $.properties
    Properties for the purchase event
  • _update_existing_onlyboolean
    Default: false
    Setting this flag to true will put the API in "Update Only" mode. When using a "user_alias", "Update Only" mode is always true.

Create Alias

Default Trigger:event = "Create Alias"

Create new user aliases for existing identified users, or to create new unidentified users.

  • external_idstringnull
    The external ID of the user to create an alias for.
  • alias_namestring
    The alias identifier
  • alias_labelstring
    A label indicating the type of alias

Identify User

Identifies an unidentified (alias-only) user. Use alongside the Create Alias action, or with user aliases you have already defined.

  • external_idstring
    The external ID of the user to identify.
  • user_aliasobject
    A user alias object. See the docs.

Getting started: web mode

  1. Go to Data & Integrations > Integrations and select the Braze entry in the Directory tab.
  2. (Optional) Select the data sources that you want to connect to your outbound integration. You can always connect data sources later. We'll only show you data sources that work with your integration.
  3. Configure your integration. See Configuration Settings below for information about individual configuration parameters.
  4. Click Enable Destination.

Web mode settings

Setting Default Description
SDK Version 4.6

The version of the Braze SDK to use
API Key

Found in the Braze Dashboard under Manage Settings → Apps → Web
SDK Endpoint sdk.iad-01.braze.com

Your Braze SDK endpoint. See more details
Allow Crawler Activity

Allow Braze to log activity from crawlers. See more details
Allow User Supplied Javascript

To indicate that you trust the Braze dashboard users to write non-malicious Javascript click actions, set this property to true. If enableHtmlInAppMessages is true, this option will also be set to true. See more details
Only Track Known Users

If enabled, this setting delays initialization of the Braze SDK until the user has been identified. When enabled, events for anonymous users will no longer be sent to Braze.
App Version

Version to which user events sent to Braze will be associated with. See more details
Content Security Nonce

Allows Braze to add the nonce to any <script> and <style> elements created by the SDK. See more details
Device Property Allow List

By default, the Braze SDK automatically detects and collects all device properties in DeviceProperties. To override this behavior, provide an array of DeviceProperties. See more details
Disable Push Token Maintenance

By default, users who have already granted web push permission will sync their push token with the Braze backend automatically on new session to ensure deliverability. To disable this behavior, set this option to true
Do Not Load Font Awesome

Braze automatically loads FontAwesome 4.7.0 from the FontAwesome CDN. To disable this behavior set this option to true.
Enable Logging

Set to true to enable logging by default
Enable SDK Authentication

Set to true to enable the SDK Authentication feature.
In-App Message Z Index

By default, the Braze SDK will show In-App Messages with a z-index of 1040 for the screen overlay, 1050 for the actual in-app message, and 1060 for the message's close button. Provide a value for this option to override these default z-indexes.
Localization en

By default, any SDK-generated user-visible messages will be displayed in the user's browser language. Provide a value for this option to override that behavior and force a specific language. The value for this option should be a ISO 639-1 Language Code.
Automatically Send In-App Messages true

When this is enabled, all In-App Messages that a user is eligible for are automatically delivered to the user. If you'd like to register your own display subscribers or send soft push notifications to your users, make sure to disable this option.
Manage Service Worker Externally

If you have your own service worker that you register and control the lifecycle of, set this option to true and the Braze SDK will not register or unregister a service worker. See more details
Minimum Interval Between Trigger Actions In Seconds 30

Provide a value to override the default interval between trigger actions with a value of your own. See more details
No Cookies

By default, the Braze SDK will store small amounts of data (user ids, session ids), in cookies. Pass true for this option to disable cookie storage and rely entirely on HTML 5 localStorage to identify users and sessions. See more details
Open Cards In New Tab

By default, links from Card objects load in the current tab or window. Set this option to true to make links from cards open in a new tab or window.
Open In-App Messages In New Tab

By default, links from in-app message clicks load in the current tab or a new tab as specified in the dashboard on a message-by-message basis. Set this option to true to force all links from in-app message clicks open in a new tab or window.
Require Explicit In-App Message Dismissal

By default, when an in-app message is showing, pressing the escape button or a click on the greyed-out background of the page will dismiss the message. Set this option to true to prevent this behavior and require an explicit button click to dismiss messages.
Safari Website Push ID

If you support Safari push, you must specify this option with the website push ID that you provided to Apple when creating your Safari push certificate (starts with "web", e.g. "web.com.example.domain").
Service Worker Location

By default, when registering users for web push notifications Braze will look for the required service worker file in the root directory of your web server at /service-worker.js. If you want to host your service worker at a different path on that server, provide a value for this option that is the absolute path to the file, e.g. /mycustompath/my-worker.js. VERY IMPORTANT: setting a value here limits the scope of push notifications on your site. For instance, in the above example, because the service ,worker file is located within the /mycustompath/ directory, appboy.registerAppboyPushMessages MAY ONLY BE CALLED from web pages that start with http://yoursite.com/mycustompath/.
Session Timeout In Seconds 1800

By default, sessions time out after 30 minutes of inactivity. Provide a value for this configuration option to override that default with a value of your own.

Web mode actions

When you're done setting things up, you can go to the Actions tab to see how we map incoming data to your integration.

You may need to add actions for this integration

While we often have default triggers for actions, we don't always add those actions as defaults. You may need to add actions to make sure that you're sending all the data that you want to send to your integration. See our actions page for help setting up actions.

Update User Profile

Default Trigger:type = "identify" or type = "group"

Updates a users profile attributes in Braze

Track Event

Default Trigger:type = "track" and event != "Order Completed"

Reports that the current user performed a custom named event.

Track Purchase

Default Trigger:type = "track" and event = "Order Completed"

Reports that the current user made an in-app purchase.

Debounce Middleware

Default Trigger:type = "identify" or type = "group"

When enabled, it ensures that only events where at least one changed trait value are sent to Braze, and events with duplicate traits are not sent. Debounce functionality requires a frontend client to work. Therefore, it cannot be used with server-side libraries or with Engage.

Updated August 20, 2026