Guides
Guides
GuidesLog In
Guides

Вranch

This guide describes how to add and configure Branch integration.

Suggest Edits

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 to Add Integration?

Please follow all steps below:

Setup iOS App

  • Integrate Branch SDK into your app
  • Match Apphud Device ID with Branch by Device ID (not User ID!) and pass attribution data:
Branch.getInstance().setIdentity(Apphud.deviceID())
Branch.getInstance().initSession(launchOptions: launchOptions) { (data, error) in
    if let data = data {
        Apphud.setAttribution(data: ApphudAttributionData(rawData: ["branch_data": data]), from: .custom, callback: nil)
    }
}

// passing attribution data from the app is supported only on iOS
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);
		});
 }

Step 2

At Apphud go to "Integrations" section and add Branch:

Step 3

❗️

Important Note

Make sure you are in LIVE environment in Branch.

Open "Account Settings" in Branch and copy"Branch Key" :

Paste copied key into "Branch live key" field in integration settings:

Step 4

Return to Branch end switch to TEST environment.

Copy test Branch Key and paste into "Branch test key" field in Apphud:

Step 5

You can enter your custom event names or disable some.

❗️

Important Note

Please, use only lower-case alpha-numeric characters (a-z and 0-9) for your in-app event names.

Step 6

Enable integration and Save changes:

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 Branch dashboard show events country as US, because our servers are located in United States. Unfortunately, there is no technical way to automatically show correct country in Branch dashboard, because Branch doesn't allow to override correct country in their events.

The only way is to write email to Branch Support from your account and ask them to whitelist recording user's country instead of server's country.

So in order to view correct user's country in country breakdown please submit a ticket to Branch Support with the following text replaced 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 User's IP Address instead of Server's IP Address as we are using Apphud service that sends our app's events server side.

Kind regards

Receive Attribution Data

By default you can send attribution from iOS code:

Branch.getInstance().initSession(launchOptions: launchOptions) { (data, error) in
    if let data = data {
        Apphud.addAttribution(data: ["branch_data": data], from: .custom, callback: nil)
    }
}

Receive attribution data from Branch using Webhooks

👍

No need to setup Branch Webhooks if attribution is passed from the app

If you are already calling Apphud.addAttribution(data: ["branch_data": data], from: .custom, callback: nil) as shown above, you do not need to setup Branch Webhooks.

For Android apps you have to setup Branch Webooks as of now.

📘

Important Note

Branch webhooks are only available on paid Data Feeds plan.

Please follow these steps:

Step 1

In your Branch integration page, please copy Webhook URL:

Step 2

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

Step 3

Using copied URL create two webhooks:

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

Step 4

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

Step 5

Now you will see the data for users that Branch was able to attribute.

In Charts section you can filter your chart by campaign, ad set or ad.

📘

Important Note

In order to receive Branch attribution data from Facebook, you should accept Facebook’s "Advanced Mobile Measurement Agreement" using this link.

Request IDFA Consent (required)

Starting iOS 14.5 access to IDFA requires user consent. You should request IDFA manually using 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 name: 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: [Apphud] billing_issue_resolved

Parameters:

  • product_id: String

-- Any other custom events --

Default event name: [Apphud] any_other_custom_event

Testing Integration

  • Make sure Branch SDK is properly integrated in your app and Branch integration is configured in Apphud.
  • Make sure Branch.getInstance().setIdentity(Apphud.deviceID()) is called.
  • If Branch's setIntegrationsTestMode() method is used, then use TEST environment in Branch.
  • Open "Liveview" tab in Branch and you will see Apphud events there.

Updated 9 days ago