Skip to main content

Branch

With our Branch integration you can:

  • Accurately track subscriptions generated from Branch campaigns, allowing you to know precisely how much revenue your campaigns generate.
  • Send trial conversions and renewals directly from RevenueCat to Branch, allowing for tracking without an app open.
  • Continue to follow your cohorts for months to know the long tail revenue generated by your campaigns.

Integration at a Glance​

Includes RevenueSupports Negative RevenueSends Sandbox EventsIncludes Customer AttributesSends Transfer EventsOptional Event Types
✅❌Requires test API key❌❌non_subscription_purchase_event expiration_event product_change_event

1. Set Branch user identity​

In order to attach attribution data to the correct user, make sure the App User Ids for RevenueCat and Branch match. The easiest way to do this is to set the Branch SDK identity to match the Purchases App User Id whether you're providing your own ids or using our randomly generated ids.

(Optional) Set a separate identity in Branch and RevenueCat​

If you prefer to keep a separate user identity between Branch and RevenueCat, set a $branchId Attribute in RevenueCat. If set, RevenueCat will use this identifier for Branch events instead of the App User Id.

📘Install the Branch SDK

You will need to add the Branch SDK to your app before you can connect it with RevenueCat.

// login
Branch.getInstance().setIdentity("my_app_user_id")

// Optional: Use a different App User ID between Branch and RevenueCat
Purchases.shared.attribution.setAttributes(["$branchId": "<custom_branch_user_id"])

// logout
Branch.getInstance().logout()

2. Send device data to RevenueCat​

The Branch integration accepts some device-specific data that can be sent to RevenueCat through reserved Attribute keys.

KeyDescriptionRequired
$idfaiOS advertising identifier UUID✅ (required) if no $idfv
$idfviOS vender identifier UUID✅ (required) if no $idfa
$gpsAdIdGoogle advertising identifier✅ (required)
$ipThe IP address of the device✅ (required)
⚠️Android ID deprecation

Due to policy changes from the Play Store, Android ID is no longer collected by RevenueCat's Android SDKs starting on versions 6.9.8+, 7.11.1+, and later major versions.

Therefore, Google's Advertising ID acts as the primary device identifier for Android devices in RevenueCat and when connecting with third-party integrations.

These properties can be set manually, like any other Attribute, or through the helper method collectDeviceIdentifiers().

import AdSupport
// ...
Purchases.configure(withAPIKey: "public_sdk_key")
// ...
Purchases.shared.attribution.collectDeviceIdentifiers()

You should make sure to call collectDeviceIdentifiers() after the Purchases SDK is configured, and before the first purchase occurs. It's safe to call this multiple times, as only the new/updated values will be sent to RevenueCat.

❗️Device identifiers with iOS App Tracking Transparency (iOS 14.5+)

If you are requesting the App Tracking permission through ATT to access the IDFA, you can call .collectDeviceIdentifiers() again if the customer accepts the permission to update the $idfa attribute in RevenueCat.

📘Import AdSupport Framework (iOS)

The AdSupport framework is required to access the IDFA parameter on iOS. Don't forget to import this into your project.

❗️Remove client-side purchase tracking

Make sure to remove all client-side tracking of revenue. Since RevenueCat will be sending events for all revenue actions, tracking purchases with the Branch SDK directly can lead to double counting of revenue in Branch.

(Optional) Send campaign data to RevenueCat​

RevenueCat itself is not an attribution network, and can't determine which specific ad drove an install/conversion. However, if you're able to collect this information from another source, such as Branch, it's possible to attach it to a user in RevenueCat using Customer Attributes as well.
The below reserved key names can be used to optionally attach campaign data to a user. This data will then be sent through to other downstream analytics integrations and accessible via APIs and webhooks.

Key
$mediaSource
$campaign
$adGroup
$ad
$keyword
$creative

3. Send RevenueCat events into Branch​

After you've set up the Purchases SDK to send attribution data from Branch to RevenueCat, you can "turn on" the integration and configure the event tokens from the RevenueCat dashboard.

  1. Navigate to your project in the RevenueCat dashboard and find the Integrations card in the left menu. Select + New

  1. Choose Branch from the Integrations menu
  2. Add your test key and live key from Branch
  3. Enter the event names that RevenueCat will send or choose the default event names
  4. Select whether you want sales reported as gross revenue (before app store commission), or after store commission and/or estimated taxes.

Branch configuration screen

📘Branch Events

We send both START_TRIAL lifecycle events and the standard trial started events to all active Branch integrations.

4. Testing the Branch integration​

You can test the Branch integration end-to-end before going live. It's recommended that you test the integration is working properly for new users, and any existing users that may update their app to a new version.

Add a sandbox API key in the RevenueCat dashboard​

Before you test the integration, make sure you have a Branch API key set in the "Branch key test" field in RevenueCat. This is required if you want the integration to trigger for sandbox purchases.

Make a sandbox purchase with a new user​

Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.

Check that the required device data is collected​

Navigate the the Customer View for the test user that just made a purchase. Make sure that all of the required data from step 2 above is listed as attributes for the user.

Check that the Branch event delivered successfully​

While still on the Customer View, click into the test purchase event in the Customer History and make sure that the Branch integration event exists and was delivered successfully.

👍You've done it!

You should start seeing events from RevenueCat appear in Branch.