Overview

Heap’s bi-directional Braze integration allows you to optimize messaging for marketers. You can use this integration to:

• Automatically capture interesting moments from Braze as events in Heap 
• Send data into Braze as Cohorts so they can be added to Braze Segments 

With this integration, digital marketers can incorporate the granular user behavioral data available from Heap into marketing campaigns without additional engineering effort. Campaigns can be more effectively personalized to better drive critical product and business outcomes, like activation, trial conversion, and retention.

Setup (Source)

These steps will walk you through setting up the integration of data from Braze to Heap using Braze Currents.

Step 1: Collect prerequisite information 

1. Confirm that your Braze account allows you to add Currents
2. Write down your Heap App Id (Account > Manage > Account Settings)
3. Decide if you want to have the “braze-” value appended to the beginning of event and property names in Heap
   1. This appended text will help you more easily identify any data that is synced from your Braze system. You may want to have this so you can better identify the large volume of data being sent by Braze into Heap. Below is an example of what the data may look like when it is added to your Heap instance.
4. Review the values you will use to match users between the two platforms. Decide which Braze user attribute you want to use: external_user_id or user_id
   • Importing events into Heap utilizes the Heap Identity value. This is a requirement that can not be changed. 
   • Braze gives you two user attributes to choose from: external_user_id or user_id. To ensure that your syncs are linking to existing users, one of these Braze attributes is required to match the Heap Identity value for a given user. Determine which of these Braze user attributes corresponds to the values you assign as identities in Heap.

Step 2: Contact your Heap Customer Sucess Manager

Contact your Heap Customer Success Manager and provide them with the prerequisite information from Step 1. If you do not have a Customer Success Manager, email sales@heap.io. From there, we will work with our partner Sureshot to set up your integration.

Step 3: Set Up Braze system current

Once the integration has been initiated, your Customer Success Manager will provide you with a URL that will use to create a new current. 

In your Braze account:

1. Navigate to Integrations > Currents
2. Click the Create New Current button
3. Paste the Endpoint URL that was provided by Heap in the corresponding field

4. Farther down the page, check the Events that you’d like to have sent to Heap

5. Click the Create Current button once you’re done.

You’ll be taken to the Current as listed in the Currents Integration page.  If you ever need to stop the integration, simply click the Stop icon next to the Current that you just enabled.

Data Format

Based on the events you selected when you set up the current, you should expect to see the following Braze events when defining an event in Heap:

• Customer Behavior and Message Engagement events (see Braze’s documentation for full list)
• Custom Events: the value for the “Name” property in Custom Events will be used as the Event Name in Heap. For example, if the event is defined as “Invite” in Braze:

Setup (Destination) (Braze Data Connector)

Prerequisites

Before you can send data from Heap to Braze, you will need to collect the following information from your Braze account:

1. Endpoint
2. Data Import Key (aka Secret)
3. API key, with appropriate permissions

Endpoint and Data Import key (aka Secret) can be found under Integrations > Technology Partners > search for Heap.

Once Heap is selected, the Cohort Key (secret) and Endpoint will be displayed. If one does not exist, click the Generate New Key button to create one. Note that this will replace any previous key if one already existed.

The API Key can be found in Braze under Settings > Developer Console.

It is a requirement that the proper permissions for this API Key are applied. Please  ensure the following permissions are checked:

Cohort Import key (aka Secret) and Endpoint can be found under Integrations > Technology Partners > search for Heap.

Once Heap is selected, the Cohort Key (secret) and Endpoint will be displayed. If one does not exist, click the Generate New Key button to create one. (note that this will replace any previous key if one already existed).

Step 1: Contact your Heap Customer Success manager

Contact your Heap Customer Success Manager and provide them with the prerequisite information. If you do not have a Customer Success Manager, email sales@heap.io. From there, we will work with our partner Sureshot to set up your integration.

Step 2: Enable Braze destination in Heap

Once the integration is set up on our end, Sureshot will provide you with a URL that needs to be added to your Heap instance to finalize the integration.

Once you are provided with a URL:

1. Navigate to Integrations > Developer Hub
2. Click Create New Integration
3. In the Webhook URL, enter the URL that Sureshot has provided
4. Set OAuth Redirect URL = blank
5. Provide a value for how users are identified in Braze (i.e. email, user ID). Typically, this will be the user ID
6. Click Save to confirm your integration setup

Step 3: Sync Heap Segments to Braze

Now you can toggle on any defined segment to sync into Braze as Cohorts. 

1. In Heap, navigate to Data > Segments
2. Click on the desired segment
3. Within the Integrations section of the pop-up, click the toggle next to Braze by Sureshot.

The first time you sync a segment from Heap to Braze, you will be asked to select which field from Heap should be sent to Braze. This can be things like Identity, email, or various Heap user properties. Click Confirm to save your choices. 

Once mapped, you can begin syncing segments to Braze. You can choose to Sync Now or set Recurring Sync to continually sync the Segment to Braze.

The segment will begin syncing immediately, and you should see a Cohort in Braze with the same segment name within 2-5 minutes. We only allow you to have 30 segments recurrently syncing to Braze at one time. After the first sync completes, the segment will update every 4 hours.

Once synced to Braze, a Cohort is created in Braze using the same name as the Heap Segment.  All users that belong to the Heap Segment will be added to the Braze Cohort.  If users are removed from the Heap segment due to the Heap segment criteria, they will be removed from the Braze Cohort during the next sync.

Creating Segment in Braze using the new Cohort

Syncing Heap segments to Braze creates a Cohort in Braze.  All users in the Heap segment will be in the Braze Cohort, and as users are added to or removed from the Heap segment, the Braze cohort will be updated (assuming that Recurring Sync was selected on the Heap segment).

Step 1: Create Segment in Braze

In Braze, navigate to Segments and click the Create Segment button. Provide a Segment name and optionally a description.

Step 2: Add the filter to the segment that uses the new Cohort

To pull up the details for any Segment in Braze, click on it from the Segments page. From the details page, under the Filters section, search for Heap Cohort.

Next, search for a Cohort value. Because the Cohort will be created with the same name as the Heap segment, search for the Heap segment name here.

You can also add any additional filter criteria that you’d like to complete the Braze Segment.