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:
- 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
. - 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 false |
user_alias object | Optional. Braze user alias object. Properties:
|
external_id string | Optional. A unique user identifier. Required if event?.user_id |
braze_id string | Optional. Identifier reserved for the Braze SDK. Required if |
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:
|
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: |
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: |
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: |
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 event?.user_id |
braze_id string | Optional. Identifier reserved for the Braze SDK. Required if |
phone string | Optional. The user's phone number. |
user_alias object | Optional. Braze user alias object. Properties:
|
_update_existing_only boolean | Optional. If 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 |
braze_id string | Optional. Identifier reserved for the Braze SDK. Required if |
phone string | Optional. The user's phone number. |
user_alias object | Optional. Braze user alias object. Properties:
|
_update_existing_only boolean | Optional. If |
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. |