Вranch

Branch is a platform to increase mobile revenue with enterprise-grade links built to acquire, engage, and measure across all devices, channels, and platforms.

How does Integration Work?

This integration works in two ways.

1. Receive Attribution Data from Branch

Once you successfully configured Branch integration, Apphud will receive attribution data from it. You can view this data on the user's page:

2. Send Subscription Events to Branch

Apphud can also send all subscription events to Branch. So you could view these events in the Branch dashboard and Branch could pass this data to their partners. This will help to measure the efficiency of your ad campaigns.

How to Add Integration?

Step 1 - Install SDKs

Install Apphud SDK.
Integrate Branch SDK into your app.
Pass attribution data to Apphud (required). See below.
Collect Device Identifiers (required). See below.
Enable User's Geo Country Breakdown (recommended). See below.
Request IDFA consent (required, iOS 14.5+). See below.

❗️
Match by Device ID, not User ID
Branch must be matched with Apphud using Device ID (Apphud.deviceID()), not User ID. Calling Branch.getInstance().setIdentity(Apphud.deviceID()) immediately after SDK initialization is required for attribution to flow correctly.

Step 2 - Preparations in Branch

Branch issues two separate API keys — one for the Live environment and one for the Test environment. You'll need both before configuring the connection in Apphud.

Live Branch Key

❗️
Important Note
Make sure you are in the LIVE environment in Branch before copying the key.

In Branch, open Account Settings and copy the Branch Key:

Test Branch Key

Switch Branch to the TEST environment and copy the test Branch Key. You'll paste both keys into Apphud in the next step.

Step 3 - Authentication

At Apphud go to Connections → Integrations (the All or Attribution tab). Click Add Connection for Branch and choose a Source in the pop-up.

Paste the previously copied keys into the Apphud connection configuration:

Branch live key (required)
Branch test key (required for sandbox / test environment)

Here is an example of a connection with live and test keys configured:

Step 4 - Additional Configuration

Environment and Revenue

Configure generic Environment and Revenue settings as described on Integrations overview → Configuration tab.

Set up filters (optional)

Navigate to Filters tab. Set up filters if needed as described on Integrations overview → Filters tab.

Step 5 - Set up Events list

Open the Events tab of the configuration. Branch uses pre-defined event names (for example, PURCHASE, START_TRIAL) combined with custom event aliases.

Apphud pre-fills default aliases like apphud_trial_started, apphud_subscription_renewed. You can customize aliases or disable some.

❗️
Event name restrictions
Use only lower-case alpha-numeric characters (a–z and 0–9) for in-app event and aliases names. Different networks may reject events with other characters.

Step 6 - Test connection (optional)

Save the connection.

For the general event submission flow testing see Integrations overview → Test connection.

To verify Branch integration end-to-end:

Make sure Branch SDK is properly integrated in your app and the Branch integration is configured in Apphud.
Make sure Branch.getInstance().setIdentity(Apphud.deviceID()) is called immediately after Branch SDK initialization.
If you use Branch's setIntegrationsTestMode() in the app, switch Branch to the TEST environment to see events.
Open the Liveview tab in Branch — you'll see Apphud events there.

Step 7 - Enable and save

Once you confirmed the connection works — Enable integration and Save again.

Pass Attribution Data to Apphud (required)

❗️
Match by Device ID, not User ID
Branch must be matched with Apphud using Device ID (Apphud.deviceID()), not User ID. Calling Branch.getInstance().setIdentity(Apphud.deviceID()) immediately after SDK initialization is required for attribution to flow correctly.

Send attribution data to Apphud (or at least the Branch Device ID). Pair setIdentity(Apphud.deviceID()) with the Branch session callback so attribution payload reaches Apphud.

Branch.getInstance().setIdentity(Apphud.deviceID())
Branch.getInstance().initSession(launchOptions: launchOptions) { (data, error) in
    if let data = data {
        Apphud.setAttribution(data: ApphudAttributionData(rawData: data), from: .branch, callback: nil)
    }
}

// On Android, the SDK call only sets identity.
// Branch attribution data must be received via Webhooks — see below.
Branch.getInstance().setIdentity(Apphud.deviceId())

Future<void> _initBranch() async {
    final deviceId = await Apphud.deviceID();
    FlutterBranchSdk.setIdentity(deviceId);
    FlutterBranchSdk.listSession().listen((data) {
        final apphudData = { "branch_data": Map<String, dynamic>.from(data) };
        Apphud.addAttribution(data: apphudData, provider: ApphudAttributionProvider.custom);
    });
}

Receive attribution data from Branch using Webhooks

👍
No need to set up Branch Webhooks if attribution is passed from the app
If you already call Apphud.setAttribution(data: ApphudAttributionData(rawData: ["branch_data": data]), from: .custom, callback: nil) as shown above, you do not need to set up Branch Webhooks.
For Android apps, Branch Webhooks are required — the Android SDK only sets identity, it does not deliver attribution data on its own.

📘
Important Note
Branch webhooks are only available on the paid Data Feeds plan.

Please follow these steps:

Step 1

In your Branch integration page in Apphud, copy the Webhook URL:

Step 2

Sign in to Branch, go to Data Feeds in the Data Import & Export section. Open Webhooks and add a new webhook:

Step 3

Using the copied URL create two webhooks:

POST webhook for every INSTALL event.
POST webhook for every OPEN event.

Step 4

As a result, you should have 2 webhooks configured in Branch — one for INSTALL and one for OPEN:

Step 5

Now you'll see attribution data for users Branch was able to attribute. In the Charts section you can filter your chart by campaign, ad set, or ad.

❗️
Important Note
In order to receive Branch attribution data from Facebook (Meta), you should accept Facebook's "Advanced Mobile Measurement Agreement" using this link.

Collect Device Identifiers (required)

iOS: Call setDeviceIdentifiers(idfa: String?, idfv: String?) method immediately after the SDK initialization. If the advertising identifier (IDFA) is not available, pass only the IDFV.
When IDFA becomes available, you can call setDeviceIdentifiers(idfa: String?, idfv: String?) again.

Android: Call Apphud.collectDeviceIdentifiers() method after the SDK initialization.
When targeting Android 13 and above, you must also declare AD_ID permission in the manifest file.

For more details, refer to Device Identifiers guide.

Enable User's Geo Country Breakdown (recommended)

📘
Important Note
By default, all data in the Branch dashboard shows the events country as US, because Apphud's servers are located in the United States. There is no technical way to automatically show the correct country in the Branch dashboard, because Branch doesn't allow overriding the country in their events.
The only way is to email Branch Support from your account and ask them to whitelist recording the user's IP address instead of the server's.

To view the correct user country in the country breakdown, submit a ticket to Branch Support with the following text (replace the placeholder with your real Branch App ID):

Subject:

Whitelist recording User IP address

Body:

Dear Branch Team!

We kindly ask you to whitelist app [BRANCH APP ID] for recording the User's IP Address instead of the Server's IP Address, as we are using the Apphud service that sends our app's events server-side.

Kind regards

Request IDFA Consent (required)

Starting iOS 14.5, access to IDFA requires user consent. You should request IDFA manually using the AppTrackingTransparency framework and pass it to Apphud. Read more here.

Events Cheat Sheet

This is a list of all possible events and their parameters that are being sent to Branch.

📘
Note
You can read more about subscription events here and parameters here.

Trial

Trial period started

Event name: START_TRIAL

Default event alias: apphud_trial_started

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
unit: String
units_count: Integer

Successful conversion from trial period to regular subscription

Event name: PURCHASE

Default event alias: apphud_trial_converted

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String

Failed conversion from trial period to regular subscription

Default event name and alias: apphud_trial_expired

Parameters:

product_id: String
reason: String

Cancellations

Trial Canceled

Default event name and alias: apphud_trial_canceled

Parameters:

product_id: String

Subscription Canceled

Default event name and alias: apphud_subscription_canceled

Parameters:

product_id: String

Autorenew disabled (Deprecated)

Default event name and alias: apphud_autorenew_disabled

Parameters:

product_id: String

Autorenew enabled

Default event name and alias: apphud_autorenew_enabled

Parameters:

product_id: String

Introductory Offer

Introductory offer started

Event name: PURCHASE

Default event alias: apphud_intro_started

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
offer_type: String
unit: String
units_count: Integer

Introductory offer renewed

Event name: PURCHASE

Default event alias: apphud_intro_renewed

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
offer_type: String
unit: String
units_count: Integer

Successful conversion from introductory offer to regular subscription

Event name: PURCHASE

Default event alias: apphud_intro_converted

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
offer_type: String

Failed conversion from introductory offer to regular subscription or failed renew

Default event name and alias: apphud_intro_expired

Parameters:

product_id: String
reason: String
offer_type: String

Refund during introductory offer

Event name: PURCHASE

Default event alias: apphud_intro_refunded

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
reason: String
offer_type: String

Regular

Subscription started

Event name: PURCHASE

Default event alias: apphud_subscription_started

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String

Subscription renewed

Event name: PURCHASE

Default event alias: apphud_subscription_renewed

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String

Subscription expired

Default event name and alias: apphud_subscription_expired

Parameters:

product_id: String
reason: String

Subscription refunded

Event name: PURCHASE

Default event alias: apphud_subscription_refunded

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
reason: String

Promo Offer

Promotional offer started

Event name: PURCHASE

Default event alias: apphud_promo_started

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
offer_id: String
revenue: Float
currency: String
offer_type: String
unit: String
units_count: Integer

Promotional offer renewed

Event name: PURCHASE

Default event alias: apphud_promo_renewed

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
offer_id: String
revenue: Float
currency: String
offer_type: String
unit: String
units_count: Integer

Successful conversion from promotional offer to regular subscription

Event name: PURCHASE

Default event alias: apphud_promo_converted

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
offer_id: String
revenue: Float
currency: String
offer_type: String

Failed conversion from promotional offer to regular subscription or failed renew

Default event name and alias: apphud_promo_expired

Parameters:

product_id: String
offer_id: String
reason: String
offer_type: String

Refund during promotional offer

Event name: PURCHASE

Default event alias: apphud_promo_refunded

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
offer_id: String
revenue: Float
currency: String
reason: String
offer_type: String

Other Events

Non renewing purchase

Event name: PURCHASE

Default event alias: apphud_non_renewing_purchase

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String

Non renewing purchase refunded

Event name: PURCHASE

Default event alias: apphud_non_renewing_purchase_refunded

Parameters:

content_items[0].$sku: String
content_items[0].$price: Float
content_items[0].$quantity = 1
revenue: Float
currency: String
reason: String

Billing Issue

Default event name and alias: apphud_billing_issue

Parameters:

product_id: String

Billing issue Resolved

Default event name and alias: apphud_billing_issue_resolved

Parameters:

product_id: String