This guide will walk you through how to send your Branch data to Heap using Branch Data Integration.


  • This guide requires you to have integrated the Branch SDK in your mobile apps.
  • You also need to be a Heap customer and have the Heap SDK installed in your app.

Required Heap SDK Versions

The code changes require the use of certain APIs in the Heap SDK, and require the following Heap SDK versions:

  • Heap for Android SDK version 1.2.0 or greater
  • Heap for iOS SDK version 6.2.1 or greater
  • Heap for React Native SDK version 0.10 or greater


Send Required Metadata to Branch

In order for Heap to correctly associate Branch events with the appropriate Heap user, it is necessary to add the Heap user ID to the Branch request metadata.

Please add the following before initializing the Branch session:


[[Branch getInstance] setRequestMetadataKey:@"$heap_user_id" value:[Heap userId]];


Branch.getInstance().setRequestMetadata("$heap_user_id", Heap.getUserId());

Retrieve your Heap Environment ID

Find your Heap environment ID and enter it into the Branch Dashboard.

  1. Log in to your Heap account and navigate to
    Account > Manage > Projects
  1. Select the appropriate project from the list and copy the environment ID for the Heap environment that you want to receive Branch events in.

Enable the Heap integration in the Branch dashboard

  1. Visit the Data Integration on the Branch dashboard.
  2. Search for Heap in the Data Integration Partner list.
  3. Select your Heap
  4. Enter the Heap Environment ID.
  5. Click Enable

Limitations with setDebug and seeing data in Branch

When integrating the SDKs, it's often useful to use setDebug to verify that your app is able to communicate with Branch servers, and is receiving deep link data. However, our upstream systems don't register test events sent using setDebug, so events will not appear in Liveview or Analytics, nor will they fire postbacks. You should disable setDebug when looking at Liveview or testing postbacks.

What Branch sends to Heap

  • Commerce Events
  • Custom Events
  • Lifecycle Event
  • Install
  • Open

Updated 29 days ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.