Braze

Send Snowplow events to Braze for real-time personalization, user tracking, and campaign automation using Braze's Track Users API.

Snowplow supports the following Braze object types:

• User attributes: Profile data and custom user properties
• Custom events: User actions and behaviors
• Purchases: Transaction data with product details

Prerequisites

Before setting up the forwarder in Console, you'll need the following from your Braze account:

• Braze REST API key with these permissions:
  • users.track
  • users.alias.new
  • users.identify
  • users.export.ids
  • users.merge
  • users.external_ids.rename
  • users.alias.update
• Braze REST API endpoint, found in Braze under Settings > APIs and Identifiers

Getting started

Configure the destination

To create the forwarder, follow the steps in Creating forwarders.

When configuring the connection, select Braze for the connection type and enter your API key and endpoint.

When configuring the forwarder, you can choose from the following Braze object types to map:

• Attributes: update user profile data
• Events: send custom user actions
• Purchases: send transaction events

Validate the integration

You can confirm events are reaching Braze by checking the following pages in your Braze account:

1. Query Builder: in Braze, navigate to Analytics > Query Builder. You can write queries on the following tables to preview the data forwarded from Snowplow: USER_BEHAVIORS_CUSTOMEVENT_SHARED, USERS_BEHAVIORS_PURCHASE_SHARED.
2. API Usage Dashboard: in Braze, navigate to Settings > API and Identifiers to see a chart of API usage over time. You can filter specifically for the API key used by Snowplow and see both successes and failures.

Limitations

Rate limits: Braze enforces a rate limit of 3,000 API calls every three seconds for the Track Users API. Because Snowplow does not currently support batching for event forwarders, this API rate limit also functions as the event rate limit. If your input throughput exceeds 3,000 events per three seconds, you will experience increased latency.

Schema reference

The sections below contain information on the fields you can send to Braze, including field names, data types, required fields, and default Snowplow mapping expressions.

User attributes

Use the user attributes object to update standard user profile fields or add your own custom attribute data to the user.

Field	Details
_update_existing_only boolean	Optional. If true, API requests will only update existing user profiles in Braze. false recommended. Default mapping: false
user_alias object	Optional. Braze user alias object. Properties: alias_name (string, required): The actual value of the alias identifier. alias_label (string, required): Indicates the type of alias. E.g. domain_userid.
external_id string	Optional. A unique user identifier. Required if user alias, braze_id, email, or phone is not provided. Default mapping: event?.user_id
braze_id string	Optional. Identifier reserved for the Braze SDK. Required if external_id, user alias, email, or phone is not provided. Not recommended for use with the Snowplow integration.
country string	Optional. ISO-3166-1 alpha-2 standard standard country code. Where the value does not meet that standard, Braze attempts to map it to a country. Where it cannot, the value will be NULL. Default mapping: event?.geo_country
current_location object	Optional. Properties: longitude (number, optional): Longitude of the user's location. latitude (number, optional): Latitude of the user's location.
date_of_first_session string	Optional. Date at which the user first used the app. Must be ISO 8601 format.
date_of_last_session string	Optional. Date at which the user most recently used the app. Must be ISO 8601 format.
dob string	Optional. The user's date of birth.
email string	Optional. The user's email address.
email_subscribe string	Optional. The user's email subscription status. Must be one of: opted_in, unsubscribed, subscribed
email_open_tracking_disabled boolean	Optional. Set to true to disable the open tracking pixel from being added to all future emails sent to this user.
email_click_tracking_disabled boolean	Optional. Set to true to disable the click tracking for all links within future emails sent to this user.
first_name string	Optional. User's first name.
gender string	Optional. The user's gender. Must be one of: M, F, O, N, P, null
home_city string	Optional. The user's city.
language string	Optional. The user's preferred language. Must be an ISO-639-1 standard language code. Default mapping: event?.br_lang
last_name string	Optional. User's last name.
marked_email_as_spam_at string	Optional. Date at which the user’s email was marked as spam. Must be ISO 8601 format.
phone string	Optional. The user's phone number.
push_subscribe string	Optional. The user's push message subscription status. Must be one of: opted_in, unsubscribed, subscribed
push_tokens array of object	Optional. Array of objects with app_id and token string.
time_zone string	Optional. The user's time zone. Must be a valid IANA Time Zone. Default mapping: event?.geo_timezone

Events

Each event object represents a single occurrence of a custom event by a particular user at the specific time. You can set and use custom event properties in messages, data collection, and personalization.

Field	Details
time string	Required. Time of the event, required. Must be ISO 8601 format. Default mapping: spTstampToJSDate(event?.collector_tstamp)?.toISOString()
name string	Required. Name of the type of event. Default mapping: event?.event_name
external_id string	Optional. A unique user identifier. Required if user alias, braze_id, email, or phone is not provided. Default mapping: event?.user_id
braze_id string	Optional. Identifier reserved for the Braze SDK. Required if external_id, user alias, email, or phone is not provided. Not recommended for use with the Snowplow integration.
phone string	Optional. The user's phone number.
user_alias object	Optional. Braze user alias object. Properties: alias_name (string, required): The actual value of the alias identifier. alias_label (string, required): Indicates the type of alias. E.g. domain_userid.
_update_existing_only boolean	Optional. If true, API requests will only update existing user profiles in Braze. false recommended. Default mapping: false
email string	Optional. The user's email address.
app_id string	Optional. Associates activity with a specific app in your Braze workspace. If set, should match a Braze App Identifier, found in Braze console's API section. Can be omitted, but incorrect values may result in data loss in Braze.
properties object	Optional. Arbitrary key-value pairs assigned to the event in Braze.

Purchases

The purchase object represents a user purchasing a single item by a user at a particular time. Each purchase object is located within a purchase array, which can represent a transaction with multiple items. The purchase object has fields that allow the Braze back-end to store and use this information for messages, data collection, and personalization.

Field	Details
time string	Required. Time of the purchase, required. Must be ISO 8601 format.
product_id string	Required. Identifier for the product purchased.
currency string	Required. ISO 4217 Alphabetic Currency Code.
price number	Required. Price per item.
external_id string	Optional. A unique user identifier. Required if user alias, braze_id, email, or phone is not provided.
braze_id string	Optional. Identifier reserved for the Braze SDK. Required if external_id, user alias, email, or phone is not provided. Not recommended for use with the Snowplow integration.
phone string	Optional. The user's phone number.
user_alias object	Optional. Braze user alias object. Properties: alias_name (string, required): The actual value of the alias identifier. alias_label (string, required): Indicates the type of alias. E.g. domain_userid.
_update_existing_only boolean	Optional. If true, API requests will only update existing user profiles in Braze. false recommended.
quantity integer	Optional. Quantity of the item purchased. Braze treats this as multiple individual purchases.
email string	Optional. The user's email address.
app_id string	Optional. Associates activity with a specific app in your Braze workspace. If set, should match a Braze App Identifier, found in Braze console's API section. Can be omitted, but incorrect values may result in data loss in Braze.
properties object	Optional. Arbitrary key-value pairs assigned to the purchase in Braze.