Braze is a comprehensive customer engagement platform that powers relevant experiences between consumers and brands they love. Braze helps brands foster human connection through interactive conversations across channels.
Braze offers a broad range of functionality via their solution and it is critically important that you work directly with your Braze representative to ensure that you are correctly planning and implementing their features. mParticle does not recommend enabling forwarding to Braze until you have completed the Braze planning process with your Braze team.
The mParticle SDK allows you to include the Braze kit which allows Braze interface components (images, layout files, etc.) and as a result supports the entire Braze feature set, which includes:
The mParticle S2S API allows you to send data server side (API reference). The S2S API supports iOS, Android and Web data. In this scenario, mParticle forwards data via Braze’s REST API which supports a limited set of features.
For server-side data to be forwarded to Braze, it must include your selected External Identity Type.
The following event types can be forwarded to Braze via S2S:
The Braze solution offers features that involve Braze-proprietary user interaction components including Newsfeed, In-App Messaging, and Feedback. In order to properly incorporate Braze with the mParticle SDK, please review the Kits section of the mParticle SDK Guide. To enable Newsfeed, In-App Messaging, and Feedback features you will need to call the Appboy embedded kit directly.
Push notifications work a bit differently for web and for mobile.
mParticle integrates with Braze to allow web push notifications to further engage your visitors. We integrated Braze’s Soft Push Prompts, which allows you to ask your user if they’d like to stay in touch before the browser alerts them to allow notifications. This is done since the browser throttles how often you can prompt the user for push notifications, and if the user denies permission, you can never ask them again. See below for directions on how to implement push notifications, which customizes Braze’s implementation instructions to work with mParticle.
To support browsers based on Chromium 51 and earlier, create a Firebase Cloud Messaging Project.
Project Settings
.Cloud Messaging
tab and note the Server Key
and Sender ID
.Configure your site
<link rel="manifest" href="/manifest.json" />
to the <head>
section of your website. Add a manifest.json file in the root of your site and enter the content below:{
"gcm_sender_id": "YOUR_CLOUD_MESSAGING_SENDER_ID"
}
service-worker.js
file to your root directory. Inside your service-worker.js
file, includeself.importScripts('https://static.mparticle.com/sdk/js/braze/service-worker.js');
mParticle hosts Braze’s service worker in order to prevent unpredictable versioning issues. Do not use Braze’s service-worker.js cdn.
Set your Cloud Messaging Key
Push Notifications
section.Configure Safari Push
Safari Website Push ID
, type in your Website Push ID
you used when generating your Safari Push Certificate (beginning with web
) and click Save
.Create a “Prime for Push” in-app messaging Campaign on the Braze dashboard.
msg-id
and a value of push-primer
.prime-for-push
custom event (or name it whatever you’d like) from the Braze dashboard. While still in the Braze dashboard, create a trigger action of whatever your custom event is (ie, prime-for-push
). In the mParticle Braze connection settings, fill in the "Soft Push" Custom Event Name
with your custom event name (ie. prime-for-push
). When this field is filled, users will be sent the Soft Push Prompt on session load.Optionally, you can change the name and location of service-worker.js
. The following example will clarify the steps:
service-worker.js
file to braze-push-worker.js
and store it in inside a directory in your root folder called thirdParty/
.Push Notification Service Worker File Location
, type in /thirdParty/braze-push-worker.js
and click Save
./thirdParty/
directory, asking for push notifications MAY ONLY BE CALLED from web pages that start with http://yoursite.com/thirdParty/.As long as the Appboy Kit is included in your app, mParticle will pass any Push Notifications from Braze to the kit for display. However, you will need to provide credentials in the Braze dashboard.
See the main iOS and Android Push Notification documentation for more detail.
The Braze kits for iOS and Android support Braze’s automatic location tracking features, provided that the appropriate app-level permissions are granted by the user.
For Android push notifications you will need to provide your Server Key in your app settings page under Push Notification Settings.
For iOS push notifications you will need to upload your APNs Push SSL certificate to Braze. See the Braze documentation for more.
mParticle supports the ability to conduct A/B testing with different integrations by sending a sample of users and their data to one integration and a different sample of users and their data to a different integration. If you are using the mParticle SDK for Braze deployment and calling Braze methods directly, when instrumenting with the mParticle SDK you must ensure that the Appboy kit is active in the App before calling an Appboy method. This is very important and ensures that you are not inadvertently calling Braze methods for apps/users that are not part of an Braze A/B sample.
mParticle supports the ability to forward server-side events for the Roku platform. Note that only data that includes your selected External Identity Type can be forwarded to Braze.
mParticle will always forward events if sent via the mParticle SDK, provided you have included the Braze kit, but will only forward events sent via the mParticle S2S API if the following conditions apply:
Braze maintains several instances. As part of the Configuration Settings, you need to specify which one your data should be forwarded to. You can tell your Braze Instance from the URL of your Braze Dashboard.
Instance | Dashboard URL |
---|---|
US 01 Cluster | https://dashboard-01.braze.com |
US 02 Cluster | https://dashboard-02.braze.com |
US 03 Cluster | https://dashboard-03.braze.com |
US 04 Cluster | https://dashboard-04.braze.com |
US 06 Cluster | https://dashboard-06.braze.com |
US 08 Cluster | https://dashboard-08.braze.com |
EU 01 Cluster | https://dashboard.braze.eu |
Check with your Braze account manager if you are unsure which Braze instance you are using.
There is also the ability to specify a Custom instance, which allows you to specify separate endpoints for REST, SDK and Javascript.
In order to activate the Braze integration, you will need your Braze API key and your “App Group REST API Key” if using the S2S API.
All commerce events will forwarded as purchase events to Braze, if the following event attributes are defined:
transaction_id
price
We also pass the currency_code
attribute of the corresponding MPProduct
object, or assume that the currency is USD if it’s not defined.
If quantity
is greater than 1, we will forward Braze a purchase event for each individual unit of the product (i.e. we’ll send two identical purchase events if quantity
equals 2).
Product attributes are mapped to the properties
node of the Braze purchase.
Your screen view events will be passed to Braze using the screen name that you passed to our logScreen
SDK method, as the event name.
If you are using automatic screen tracking in our Android SDK, the automatically-generated screen view events will be forwarded to Braze using the name of the associated Activity class.
To send session start and end events S2S to Braze, enable the Forward Session Events
connection setting. Once enabled, session start and end events will be forwarded to Braze as custom events with the names Session Start
and Session End
. When available, session IDs will also be sent in the session_id
property on all session start/end, screen view, and custom events.
All custom events will be forwarded to Braze using the event name that you passed to your logEvent
SDK method. All event attributes will be forwarded to Braze as Braze custom event properties using the attribute names you passed to your logEvent
SDK method as well.
The table below describes how the mParticle integration maps user attributes to Braze’s profile attributes.
mParticle Field | Braze Profile Attribute | Description |
---|---|---|
User Identity of type CustomerId |
external_id |
|
User Attribute $FirstName |
first_name |
|
User Attribute $LastName |
last_name |
|
User Identity of type Email |
email |
|
Derived from User Attribute $Age ) |
dob |
mParticle estimates the user’s date of birth by subtracting $Age from the current year, and using January 1st as the month and day. For example, if $Age is 10 and the current year is 2014, we’ll forward the user’s date of birth as 2004-01-01. If an exact birth date is desired, set a user attribute called dob with user’s birth date. When both $Age and dob user attributes are sent, one value may override the other when mParticle forwards data to Braze. So it is recommended that one of them is toggled Off in mParticle’s data filter for Braze. |
User Attribute $Country |
country |
|
User Attribute $City |
home_city |
|
User Attribute $Gender |
gender |
|
User Attribute $Mobile |
phone |
|
Derived from SDK opt-out status | email_subscribe |
This is based on calling the OptOut (setOptOut in Android) SDK method . It will be set to opted_in when called with a value of true and will be set to unsubscribed when called with a value of false. |
push_tokens |
Because Braze can only accept a single push token for each app/user pair, we will forward the most recently-registered push token to Braze per user and per app. | |
User Identity of type Facebook |
facebook |
|
User Identity of type Twitter |
twitter |
By default, mParticle forwards all available user attributes to Braze, including attributes added during profile enrichment. You can disable this behavior in the Connection Settings. Only data which is sent to Braze Server to Server can be enriched.
Setting Name | Data Type | Default Value | Description |
---|---|---|---|
API Key | string |
Your app’s API Key can be found in your Braze dashboard. | |
External Identity Type | enum |
Customer ID | The mParticle User Identity Type to forward as an External ID to Braze. |
Email Identity Type | enum |
The mParticle User Identity Type to forward as the Email to Braze. | |
Braze Instance | enum |
US 03 Cluster | Specify which cluster your Braze data will be forwarded to. Please ensure you are contractually authorized to use the EU cluster if you select that option. If you choose ‘Custom’, you will need to provide separate endpoints for your SDK, Server, and Web data. |
Setting Name | Data Type | Default Value | Platform | Description |
---|---|---|---|---|
App Group REST API Key | string |
All | The App Group REST API Key can be found in the developer console section of the Braze dashboard. This field is optional when sending in data via the SDK, but is required for using the S2S API. | |
Braze SDK Session Timeout | string |
All | Braze SDK time interval for session time out in seconds. | |
Push Enabled | bool |
True | iOS, tvOS, Android | Forward GCM registration IDs to the Braze SDK and enable Braze push notifications. |
Event Attributes that add to array | Custom Field |
iOS, tvOS, Android, Roku | Select your mParticle event names and event attributes and enter the corresponding Braze custom attribute array name you want the event attribute ADDED to. | |
Event Attributes that remove from array | Custom Field |
iOS, tvOS, Android, Roku | Select your mParticle event names and event attributes and enter the corresponding Braze custom attribute array name you want the event attribute REMOVED from. | |
Event Attributes that set to custom attribute value | Custom Field |
iOS, tvOS, Android, Roku | Select your mParticle event names and event attributes and enter the corresponding Braze custom attribute you want the event attribute to map to. Note each time this event attribute is present, it will get sent to Braze and overwrite any previously sent value. | |
Braze SDK Flush Interval | string |
iOS, tvOS | Braze SDK data flush internal in seconds (iOS only). Refer to Braze sdk doc for “ABKFlushIntervalOptionKey”. | |
Braze SDK Request Policy | string |
iOS, tvOS | Braze SDK request policy at app start time (iOS only). Refer to Braze sdk doc for “ABKRequestProcessingPolicyOptionKey”. | |
Braze SDK Minimum Time Interval Between Triggers | string |
iOS, tvOS | Braze SDK minimum time interval in seconds between triggers (iOS only). Refer to Braze sdk doc for “ABKMinimumTriggerTimeIntervalKey”. | |
User Tags Value | enum |
“true” | All but Web | Select the value to be sent to Braze for user tags. The possible values are null or “true”. When “true”, it will be affected by the parameter Enable type detection. |
Braze SDK Collect IDFA? | bool |
False | iOS, tvOS | Informs the Braze Kit whether to collect IDFA. |
Braze SDK Disable Automatic Location Tracking | bool |
False | iOS, tvOS | Informs the Braze Kit whether to disable automatic location tracking at app startup time |
Include Enriched User Attributes | bool |
True | All | If enabled, mParticle will forward enriched user attributes from the existing user profile. Only data which is sent to Braze Server to Server can be enriched. |
Send User Attribute Lists as Arrays | bool |
False | All | If checked, mParticle will send each user attribute list server-side as an array, rather than a comma-separated string |
Enable type detection for user attributes | bool |
False | All but Web | By default, all platforms (except for web) send user attributes as strings unless there are special Braze reserved user attributes. Checking this will force user attributes to be sent as parsed data types where possible. Please note that Braze refers to these as Custom Attributes. |
Forward Screen View Messages | bool |
False | All | If enabled, all screen view messages will be forwarded to Braze as separate events. Not supported for S2S requests. |
Forward Session Events | bool |
False | All | If enabled, all session start and end events will be forwarded to Braze as separate events. Session IDs will also be sent with events when populated. |
Soft Push Custom Event Name | string |
Web | The custom event name that shows up in your Braze dashboard when priming your user for push notifications. Braze recommends “prime-for-push”. When filled in, users will be sent a Braze In-App message on session load | |
Push Notification Service Worker File Location | string |
Web | Optional - If the “service worker.js” file is not located in your root directory, then this field is the relative path, starting with ”/” and including the filename.js. Please view integration docs for more information | |
Safari Website Push ID | string |
Web | The unique identifier for your Website Push ID, starting with the string “web”, from the Apple Developer website | |
Automatically display new in-app messages | bool |
True | Web | Automatically display new in-app messages when they come in from the server. |
Forward Page Name as Braze Event Name | bool |
False | Web | If enabled, the Page Name that is sent to Braze is the first argument in mParticle.logPageView(“PageName”). Otherwise the path will be used. For S2S requests, enabling this setting will send the event name as-is. Otherwise Viewed will be added to the event name. |
Replace SKU as Braze Product Name | bool |
False | Web | If enabled, the SKU replaces Product Name when sent to Braze. By default, Web sends Product Name to Braze. New customers should check this to be consistent with iOS/Android which sends SKU by default. |
Enable HTML within in-app messages | bool |
False | Web | Enable HTML within in-app messages. This correlates to the enableHtmlInAppMessages setting of the Braze SDK. |
Do not Load FontAwesome | bool |
False | Web | Disable loading of FontAwesome from the FontAwesome CDN. Note that if you do this, you are responsible for ensuring that FontAwesome is loaded - otherwise in-app messages may not render correctly. |
Was this page helpful?