Attribution API

Overview

The Branch Mobile SDK uses a RESTful API (v1/open) for deep linking and session attribution. The instructions below cover how to supply a payload of attribution properties to this API server-side. Every time the API is called, it will track an INSTALL, REINSTALL, or OPEN event in Branch and return deep link data in the response if the session is attributed.

By bypassing the SDK, developers will be responsible for session management (when & where the v1/open API is called), handling poor or no connectivity, persisting data locally, retrieving values like IP address, tracking downstream conversions, creating shareable deep links, etc. To achieve feature parity with the SDK, one would need to duplicate the code in the SDK.

It is highly recommended that all apps use the Branch Mobile SDK when possible.

📘

API Access is restricted

The ability to directly call the v1/open API is restricted to select enterprise accounts. Please contact your Branch Account Manager to confirm if your account is eligible for enablement.

Prerequisites

• App is setup in the Branch dashboard with default link redirects, your app.link domains, a URI scheme, Universal Links, and you have access to your API & Secret keys
• Account has been enabled to access the v1/open API

📘

Dashboard & In-App setup required

Successful use of the v1/open API will require setup steps in the Branch dashboard and in your mobile app

API Setup

The network request to v1/open should occur when you are successfully notified the app was brought to the foreground. Branch defines an app lifecycle as a session of when your application is launched (cold start, or if it was present in the iOS or Android task manager), and comes to the device’s foreground.

Endpoint Specifications

• Endpoint: https://api2.branch.io/v1/open
• Method: POST
• Payload Format: JSON
• Required Header: The device's public IP address must be set using -H "X-IP-Override: xx.xx.xx.xx" (it is critical this uses the device's IP, and not your server's IP)
• Required Header: -H 'content-type: application/json'
  

POST body parameters

Example Requests

iOS

curl -v -d '{
 "branch_key": "TODO",
 "branch_secret": "TODO",
 "server_to_server": true,
 "app_version": "1.12.4",
 "os": "iOS",
 "os_version": "10.0",
 "model": "iPhone",
 "screen_height": 2208,
 "screen_width": 1242,
 "facebook_app_link_checked": false,
 "user_agent": "{FULL_USER_AGENT_HERE}",
 "hardware_id": "D5B89252-FCF8-4065-88FC-B70F49186988",
 "hardware_id_type": "idfa",
 "ios_vendor_id": "0C381C08-B808-4C25-BE51-B00BC165B5F8",
 "is_hardware_id_real": true,
 "ad_tracking_enabled": true,
 "custom_param_1": "Parameter 1",
 "custom_param_2": "Parameter 2",
 "custom_param_3": "Parameter 3"
}' "https://api2.branch.io/v1/open" -H "X-IP-Override: 1.2.3.4"

Android

curl -v -d '{
 "branch_key": "TODO",
 "branch_secret": "TODO",
 "server_to_server": true,
 "app_version": "1.12.4",
 "os": "Android",
 "os_version": 26,
 "model": "SM-G960U1",
 "screen_height": 2076,
 "screen_width": 1080,
 "facebook_app_link_checked": false,
 "user_agent": "{FULL_USER_AGENT_HERE}",
 "hardware_id": "fae098e4605e79c3",
 "google_advertising_id": "ea31e5e0-1aa5-4181-91d7-0b56524e0274",
 "advertising_ids": {
    "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
 },
 "google_search_install_referrer": "referrer_value_here",
 "clicked_referrer_ts": 1574699946,
 "install_begin_ts": 1574699955,
 "is_hardware_id_real": true,
 "ad_tracking_enabled": true,
 "custom_param_1": "Parameter 1",
 "custom_param_2": "Parameter 2",
 "custom_param_3": "Parameter 3"
}' "https://api2.branch.io/v1/open" -H "X-IP-Override: 1.2.3.4"

📘

Rate limits on non-referred OPENs

Branch by default will rate limit non-referred OPEN events (app sessions not sourced by a link) per IP address, to once every 4 hours (contact your Branch Account Manager to confirm the exact limit for your account). Rate limited sessions will still return deep link data in the network request, but their data will not appear in the dashboard nor in your exports.

📘

Rate limits on high-frequency pings

Because the v1/open API is intended to measure a user's app session, we will return 429 responses if the app starts sending requests for the same user in rapid succession. Because normal user behavior is not to open & close an app in rapid succession, this scenario will likely only occur during testing. If you run into this, please wait a few minutes before resuming testing (or try changing the device metadata in your request).

📘

NativeLink

In order to implement NativeLink (learn more) and benefit from a guaranteed mechanism for deep linking, you will need to check the pasteboard on the first install. If it contains a URL, then examine the contents of the pasteboard. If it contains a Branch link, please send the full URL in the request body for key local_url.

For an example of checking the pasteboard on iOS, see this code snippet in our open-source iOS SDK.

Handling deep link data

When the v1/open request is made, the app session can be attributed to a deep link click. Regardless if the session is attributed, the API will always return a 200 response with some contextual data included in the JSON response payload. If the session was attributed to a Branch link, this payload will include the link's deep link data for your in-app logic to use to execute your deep link UX.

Samples responses are listed below, but a few key parameters to be aware:

Example organic response

{
   "session_id": "xxxx",
   "randomized_device_token": "xxxx",
   "link": "https://bnc.lt/j/adsf",
   "data": "{\"+clicked_branch_link\":false,\"+is_first_session\":false}"
}

Example organic response, with server_to_server_identity enabled

{
   "session_id": "xxxx",
   "randomized_bundle_token": "xxxx",
   "identity": "xxxx",
   "randomized_device_token": "xxxx",
   "link": "https://bnc.lt/j/adsf",
   "data": "{\"+clicked_branch_link\":false,\"+is_first_session\":false}"
}

Example response when session started by a non-Branch Deep Link

{
   "session_id": "823602214081710808",
   "data": "{\"+non_branch_link\":\"https://branch.io/\",\"+clicked_branch_link\":false,\"+is_first_session\":false}",
  "randomized_device_token": "823601870295755491"
}

Example response when session started by a Branch Deep Link

{
   "randomized_device_token": "823600311503935224",
   "link": "https://example.app.link/X7OsnWv9TF",
   "session_id": "429691081177874743",
   "data": "{
            "$canonical_url": "https://example.com/home?utm_campaign=test",
            "$desktop_url": "http://example.com/home",
            "$og_description": "My Content Description",
            "$og_image_url": "http://lorempixel.com/200/200/",
            "$og_title": "46D6D28E-0390-40E4-A856-BD74F34D24C8",
            "+click_timestamp": 1503684563,
            "+clicked_branch_link": true,
            "+is_first_session": false,
            "+match_guaranteed": true,
            "custom": "blue",
            "~campaign": "new launch",
            "~channel": "facebook",
            "~creation_source": 3,
            "~feature": "sharing",
            "~id": 429691043152332059,
            "~referring_link": "https://example.app.link/X7OsnWv9TF",
            "~stage": "new person",
            "~tags": ["one","two"]
   }"
}

In-App Setup

iOS

Configuration Updates

1. Add your URI scheme to the info.plist
2. Add your Branch app.link and alternate.app.link domains to the Associated Domains
   

App launch data needed for API request

1. Retrieve the device ID (IDFA or IDFV) when available
2. Retrieve the device’s public IP
3. Retrieve the device’s User-Agent
4. Examine the AppDelegate's openURL: function for a URI. If a URI containing a query parameter link_click_id is present, store the query parameter's value for use in the session's API network request (i.e., if the URI example://open?link_click_id=1234 opens the app, you will retrieve the “1234” value)
5. Examine the AppDelegate's continueUserActivity: function for a webpageURL in the NSUserActivity parameter. If a URL is found (regardless if it's a Branch link), store the entire URL value for use in the session's API network request.
   

[OPTIONAL] To support Apple Search Ads

NEW FRAMEWORK:

• For S2S integrations, you will need to retrieve the new token and send to Branch on the install as apple_attribution_token

Please refer to the new AdServices developer documentation on how to retrieve the token.

1. Import AdServices.framework
2. Request attribution token (see sample code). This should be available from Apple within 50ms.
3. The token has a 24 hr TTL, so send to Branch within that time in order to use it for attribution.

See sample code for obtaining the Apple Attribution token:

func appleAttributionToken() -> String? {
        if #available(iOS 14.3, *) {
            return try? AAAttribution.attributionToken()
        }
        return nil
    }

+ (NSString *)appleAttributionToken {
#if !TARGET_OS_TV
    if (@available(iOS 14.3, *)) {
        NSError *error;
        NSString *appleAttributionToken = [AAAttribution attributionTokenWithError:&error];
        if (!error) {
            return appleAttributionToken;
        }
    }
#endif
    return nil;
}

OLD FRAMEWORK: All steps below should only occur for the INSTALL session:

1. Upon app launch, do not call v1/open, and first query the Apple Search Ads API. Apple's API is know to have high latency and operates at a race condition with its ad click (i.e., it must process the search click before it can respond to its attribution API), so give a 2 second buffer before calling Apple's Attribution API.
2. Implement retry logic (Branch's SDK uses 2 second delays between retries) if your request times out after 5 seconds, or if the response returns as False or Error Code [0,2,3]
3. If a successful response is received, base64 encode the entire API response, and add it to the search_ad_encoded property of the v1/open. Do not populate this in v1/open if apple did not attribute the session, and do not repeat this process during subsequent app sessions.

Android

Configuration Updates

1. Add your URI scheme to the Android Manifest
2. Add your Branch app.link and alternate.app.link domains to the Android Manifest
   

App launch data needed for API request

1. Retrieve the device ID (GAID or Android_ID when available
2. Retrieve the device’s public IP
3. Retrieve the device’s User-Agent
4. Examine the intent that opened your MainActivity for a URI. If a URI containing a query parameter link_click_id is present, store the query parameter's value for use in the session's API network request (i.e., if the URI example://open?link_click_id=1234 opens the app, you will retrieve the “1234” value)
5. Examine the intent that opened your MainActivity for a web URL. If a URL is found (regardless if it's a Branch link), store the entire URL value for use in the session's API network request.
   

[OPTIONAL] To support Google Play Install Referrer

All steps below should only occur during the INSTALL session:

1. Upon app launch, query the Google Play Install Referrer library for the referrer Url, click timestamp, and install timestamp
2. Examine the referrer Url for a “link_click_id” query parameter, and if present, retrieve its value for use in the v1/open link_identifier property. This may appear in the referrer Url as &link_click_id=<value> or &link_click_id-<value>, but in either scenario you're only extracting the <value> part.
3. Examine the referrer Url for a “google_search_install_referrer” query parameter, and if present, retrieve its value for use in the v1/open google_search_install_referrer property. This may appear in the referrer Url as &google_search_install_referrer=<value> or &google_search_install_referrer-<value>, but in either scenario you're only extracting the <value> part.

Tracking Downstream Events

Every time the v1/open API is called it will track an INSTALL, REINSTALL, or OPEN event in Branch. To track additional downstream conversion events (i.e., PURCHASE), you will need to use the HTTP API instructions for our Commerce, Content, Lifecycle, and Custom events.

When tracking downstream conversion events, please address the following items:

• If the request is made from the device, we will automatically retrieve the IP address from the request. If the request is made from a server, the user's IP address must be set via the following header: -H "X-IP-Override: xx.xx.xx.xx"
• Set the device’s user agent in the request body’s user_data.user_agent
• For events occurring in app, populate a device ID with IDFA (and fallback to IDFV) in iOS, or GAID (fallback to android_id) in Android
• For events occurring on web, retrieve a Browser fingerprint via the Branch web SDK, to be included in the event call
• Populate the developer_identity property whenever a persistent user ID is available (Best Practices for user IDs)

Server-to-Server Integrations with the TUNE API

All clients scoping a net new integration, should only consider the Branch SDK or server-to-server integration, and should NOT integrate with the TUNE API server-to-server. Any apps that originally integrated TUNE server-to-server, before TUNE was acquired by Branch, can find the API specs below for troubleshooting purposes:

• Tracking Sessions
• Tracking COMMERCE, LIFECYCLE, CONTENT Events
• Tracking CUSTOM Events

For existing TUNE server-to-server integrations, it is good to confirm the following metadata properties are accounted for, to ensure TUNE integrations can leverage Branch's latest attribution methodologies:

📘

local_ip is not supported on TUNE API calls

local_ip is leveraged for Branch's Predictive Modeling capabilities, but this cannot be set in TUNE API calls. This will not prevent attribution on the TUNE API endpoint.