Skip to main content

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:

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:

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.

FieldDetails
_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.

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

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