概述

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 INSTALLREINSTALL, 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 访问受到限制

直接调用 v1/open API 的功能仅限于部分企业帐户。请联系您的 Branch 客户经理,以确认您的帐户是否符合条件。

先决条件

  • 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
  • 帐户已允许访问 v1/open API

📘

需要进行操作后台 (Dashboard) 以及应用内设置

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

API 设置

当成功通知您将应用带入前台时,会出现 v1/open 网络请求。当应用启动(冷启动,或者存在于 iOS 或 Android 任务管理器中)并在设备前台运行时,Branch 会将这一应用生命周期定义为一个会话。

Endpoint 详述

  • Endpoint: https://api2.branch.io/v1/open
  • Method:POST
  • 有效负载格式: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 参数

属性

数据类型

描述

例如

branch_key

String

必需项您的实时 API key,可从实时环境的操作后台 (Dashboard) 帐户设置中获得

key_live_example

branch_secret

String

必需项您的实时 API Secret,可从实时环境的操作后台 (Dashboard) 帐户设置中获得

secret_live_example

server_to_server

Boolean

REQUIRED Always set to true

真正

app_version

String

必需项您的应用版本

"1.12.4"

操作系统

String

REQUIRED Only accepts Android oriOS

“Android”

os_version

String

REQUIRED The version of the device's OS (e.g. “23” for Android or “9.1.2” for iOS respectively. Will accept any value, preferred default to “NA”. This cannot be blank.)

"13.2.2"

user_agent

String

必需项设备的用户代理

"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6 Build/MOB31E) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.81 Mobile Safari/537.36"

hardware_id

String

REQUIRED In iOS, populate with the IDFA if it's available, otherwise fallback to IDFV. On Android, populate with the ANDROID_ID (hardware id). If no device ID is available, do not include in request.

iOS: "D5B89252-FCF8-4065-88FC-B70F49186988"

Android: "fae098e4605e79c3"

hardware_id_type

String

REQUIRED - iOS ONLY Value confirms whether the iOS ID in the hardware_id property is an "idfa" or "vendor_id" (do not include in request, if hardware_id is not populated)

"idfa" or "vendor_id"

ios_vendor_id

String

REQUIRED - iOS ONLY The IDFV if it's available, otherwise do not include in request.

"0C381C08-B808-4C25-BE51-B00BC165B5F8"

google_advertising_id

String

REQUIRED - ANDROID ONLY The Google Advertising ID if it's available, otherwise do not include in request

"ea31e5e0-1aa5-4181-91d7-0b56524e0274"

advertising_ids

Object

ANDROID ONLY The set of Advertising IDs if it's available, otherwise do not include in request. Can include identifiers like OAID

"advertising_ids": { "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc" }

is_hardware_id_real

Boolean

REQUIRED Set to false if the hardware_id property cannot be populated, otherwise default to true

真正

ad_tracking_enabled

Boolean

REQUIRED A value used to determine whether the IDFA or GAID can be used for advertising purposes. If Limit Ad Tracking should be enabled, do not include in the request.

真正

local_ip

String

This is the device's local IP address, if one is available. This is incremental to the required IP header. An optional but highly recommended data metadata that improves attribution accuracy.

“192.168.1.153”

screen_height

整数

Height of the device’s screen. An optional but useful data metadata that improves attribution accuracy.

2208

screen_width

整数

Width of the device’s screen. An optional but useful data metadata that improves attribution accuracy.

1242

link_identifier

String

a URI opens the app, check for a link_click_id query, and populate with that value (if missing, do not include in request)
link_click_id may also be sourced by the Google Install Referrer

“823569794275788167”

universal_link_url

String

使用打开应用的 Branch 或非 Branch 网址填充(如果缺少,则不包含在请求中

"https://branch.app.link/example?utm_medium=test"

android_app_link_url

String

使用打开应用的 Branch 或非 Branch 网址填充(如果缺少,则不包含在请求中

"https://branch.app.link/example?utm_medium=test"

facebook_app_link_checked

Boolean

设置为 false to ensure we retrieve deep links from Facebook's deferred deep linking API (requires adding your Facebook App Secret to the [Branch dashboard](https://help.branch.io/using-branch/docs/facebook-app-install-ads#section-setup))

真正

install_referrer_extras

String

ANDROID ONLY Populate it with the value of the full Android PlayStore Install Referrer URL. Only include in the app's first session, if it's available.

"utm_source=some_source&utm_medium=preload&utm_campaign=null&gclid=Cj0KCQiA7IDiBRCLARIsABIPohhqdEU00f-Obte_OIVTbjPo-iLDBjkhj8ov="

google_search_install_referrer

String

ANDROID ONLY The value of the google_search_install_referrer query parameter on the referrerUrl from the Google Install Referrer. Only include in the app's first session, if it's available.

“7AXhuEQs1U”

clicked_referrer_ts

Long

ANDROID ONLY The referrer click timestamp collected from the Play Install Referrer library.
Only include in the app's first session, if it's available.

1573098834

install_begin_ts

Long

ANDROID ONLY The install begin timestamp collected from the Play Install Referrer library. Only include in the app's first session, if it's available.

1573098843

apple_attribution_token

String

iOS ONLY Attribution Token used for Apple Search Ads . used to call the Apple Search Ads Attribution API. The token has a 24 hr TTL, so send to Branch within that time in order to use it for attribution.

"c7ya5fQsXrqhCiG0eQTvpS8+tNpBom1RwlDmWEXGNqIj1AOn/VDlqgKq9CaJzzFeR8G3dEeMQBJc60R4CxIx..."

search_ad_encoded

String

DEPRECATED ⚠ iOS ONLY Base64 encoded string of the entire response from the Apple Search Ads API. Only include in the app's first session, if it's available.

"eyJWZXJzaW9uMy4xIjp7ImlhZC1wdXJjaGFzZS1kYXRlIjoiMjAyMC0wNi0yOVQxODo1MDoxNloiLCJpYWQta2V5d29yZCI6IktleXdvcmQiLCJpYWQtYWRncm91cC..."

first_session

Boolean

Identifies if this is the first time the user opened the app. If true, Branch will check if we saw the user download the app before, and mark the session as a reinstall if yes, and an install if no. If this value was set to false, Branch will count the session as an open.

真正

server_to_server_identity

Boolean

Setting to true enables the ability to set an randomized_bundle_token property in v1/open requests and returns a value in the response. Do not set this property in the request, if this feature will not be used.

false

randomized_bundle_token

Boolean

If server_to_server_identity is true, Branch returns a new identity value in any request that does not set randomized_bundle_token. After the first request, this property must be hardcoded with the randomized_bundle_token received in the first network response. Failure to return this value in subsequent requests severely limits the ability to connect different events for that user.

“791040498773585647”

身份

String

If server_to_server_identity is true, this property can be used to associate a custom user ID with Branch's anonymous identity. You should never use personal user information here, and all values should be encrypted before being passed to Branch.

“U1923847128356”

tracking_disabled

Boolean

If set to true, Branch will not store any data from this app session. The network response can still return deep link data for processing, but no information will be stored afterwards.

false

disable_ad_network_callouts

Boolean

If set to true, you can use the Branch dashboard to selectively remove sessions with this flag from being sent to ad networks

false

local_url

String

(Optional, for NativeLink) Populate with a Branch web url that is present on the clipboard on the very first open (if missing, do not include in request)

"https://branch.app.link/example?utm_medium=test"

referrer_gclid

String

ANDROID ONLY (Optional, for Google AdWord Campaigns) Extract the value of gclid from Android PlayStore Install Referrer URL. Utilized for tracking downstream events on Google Adwords when user opts out on Android 12+ devices (if missing, do not include in request)

"CjwKCAiA3L6PBhBvEiwAINlJ9Chixm216y8kYYJ1K94dm4FEkOgFfhIdKQdjWsYB7FqE7rf_zkGNEhoCuIEQAvD_BwE"

gbraid

String

IOS ONLY (Optional, for Google AdWord Campaigns) Extract the value of gbraid from the referring url/uri for the app session. Utilized for tracking downstream events on Google Adwords when users are opted out of ATT (if missing, do not include in request)

"CjwKCAiA3L6PBhBvEiwAINlJ9Chixm216y8kYYJ1K94dm4FEkOgFfhIdKQdjWsYB7FqE7rf_zkGNEhoCuIEQAvD_BwE"

custom_param_1

String

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

"PARAMETER 1"

custom_param_2

String

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

"PARAMETER 2"

custom_param_3

String

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

"PARAMETER 3"

示例请求

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"

📘

未推荐 OPEN 的频率限制

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.

📘

高频 ping 的频率限制

由于 v1/open API 旨在测量用户的应用会话,因此如果该应用开始快速连续向同一用户发送请求,我们将返回429个请求结果。由于正常的用户行为不是快速连续打开和关闭应用,因此这种情况很可能仅在测试期间发生。如果遇到这种情况,请等待几分钟,然后再恢复测试(或尝试更改请求中的设备 metadata)。

📘

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.

处理深度链接数据

发出 v1/open 请求后,可以将应用会话归因于深度链接点击。无论会话是否属于属性,API 都将始终返回200请求结果,并在 JSON 请求结果有效负载中包含一些上下文数据。如果会话归因于 Branch Link,则此负载将包含该链接的深度链接数据,供您的应用内逻辑用来执行深度链接 UX。

请参照下面列出的请求结果示例,并特别注意一些关键参数:

参数

描述

randomized_bundle_token

If you set server_to_server_identity to TRUE in the v1/open request, you must ensure the value returned here is used in the randomized_bundle_token property of all v1/open requests moving forward for that device.

+clicked_branch_link

This will tell you if the current app session was sourced via Branch deep link. This can be used as a conditional trigger that dictates if you use Branch-specific or other deep link routing logic.

+non_branch_link

If a non-Branch deep link opened your app (i.e., a Universal Link), you can retrieve that link from this key.

+is_first_session

This will be TRUE if Branch has never seen this user's device install the app before

+match_guaranteed

This will be TRUE if Branch was able to match the app session to the browser click with 100% certainty. This can be used as a conditional trigger for use cases where you have zero risk threshold for a false positive (this should NOT be used in most instances)[Not applicable to SAN attributed Install].

$canonical_url

This will contain a web url that you can use for deep link routing. If your app was already setup to route off Universal Links or Android App Links, you can pass this value into that pre-existing routing logic.

$deeplink_path

This will contain a URI relative path that you can use for deep link routing. If your app was already setup to route off URI schemes, you can pass this value into that pre-existing routing logic.

自然请求结果示例

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

启用 server_to_server_identity 时的自然请求结果示例

{
   "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}"
}

非 Branch 深度链接启动会话时的请求结果示例

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

Branch 深度链接启动会话时的请求结果示例

{
   "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"]
   }"
}

应用内设置

iOS

配置更新

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

API 请求所需的应用启动数据

  1. Retrieve the device ID (IDFA or IDFV) when available
  2. 获得设备的公共 IP
  3. 获得设备的 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.

[可选]支持 Apple Search Ads

NEW FRAMEWORK:

  • 对于 S2S 集成,您将需要检索新令牌并在安装时以 apple_attribution_token 形式发送给 Branch

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

  1. 导入 AdServices.framework
  2. 请求归因令牌(请参见示例代码)。Apple 应该在 50 毫秒内响应。
  3. 令牌具有 24 小时 TTL,因此请在该时间内发送给 Branch,以便将其用于归因。

请参阅获取 Apple 归因令牌的示例代码:

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. 如果您的请求在5秒钟后超时,或者请求结果返回为 False 或 Error Code [0,2,3],则实现重试逻辑( Branch 的 SDK 在重试之间使用2秒的延迟
  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

配置更新

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

API 请求所需的应用启动数据

  1. Retrieve the device ID (GAID or Android_ID when available
  2. 获得设备的公共 IP
  3. 获得设备的 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.

[可选]以支持 Google Play Install Referrer

以下所有步骤仅应在 INSTALL 会话期间发生

  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.

追踪下游事件

Every time the v1/open API is called it will track an INSTALLREINSTALL, 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:

  • 如果请求是从设备发出的,我们将自动从请求中获得 IP 地址。如果请求来自服务器,则必须通过以下 header 设置用户的 IP 地址: -H "X-IP-Override: xx.xx.xx.xx"
  • 在请求正文中设置设备的用户代理 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)

使用 TUNE API 进行服务器间 (server-to-server)的集成

寻求新的净集成的所有客户端,应该只考虑 Branch SDK 或服务器间 (server-to-server)的集成,而不应该与 TUNE API 服务器间 (server-to-server)集成。在 Branch 收购 TUNE 之前,任何最初将 TUNE 服务器间 (server-to-server)集成的应用都可以找到以下 API 说明以进行问题排查:

对于现有的 TUNE 服务器间 (server-to-server)集成,最好确认已考虑以下 metadata 属性,以确保 TUNE 集成可以利用 Branch 的最新归因方法:

Key

描述

ios_ifa

REQUIRED - iOS The IDFA if it's available

ios_ad_tracking_disabled

必要项-iOS如果要使用 ios_ifa 参数,则必须指定 ios_ad_tracking_disabled 参数以指示最终用户是否已启用受限广告追踪(1表示已启用/受限)。

ios_ifv

REQUIRED - iOS Populate with the IDFV

google_aid

REQUIRED - Android The Google Advertising ID if it's available. Formatted as uppercase with hyphens. AAAAAA-BBBB-CCCC-11111-2222222222222

google_ad_tracking_disabled

必要项-Android如果要使用 google_aid 参数,则必须指定google_ad_tracking_disabled 参数以指示最终用户是否已启用受限广告追踪(1表示已启用/受限)。

os_id

REQUIRED - Android Populate with the ANDROID_ID (hardware id), if google_aid cannot be populated

device_id

必要项-Windows Windows 硬件 ID

windows_aid

必要项-Windows Windows 广告标识符(AID)是用于广告的唯一、特定于用户和设备的可重置 ID,表示为字母数字字符串,格式为大写且无冒号(例如,“ AAAAAABBBBCCCC111122222222222”)。禁用广告 ID 功能时,此值为空字符串。

referral_url

必要项Android 和其第一个应用打开,包括 Google Play install referrer。

对于 Android 和 iOS 上的所有其他打开,请包括导致打开的 URL(深度链接)。

device_ip

记录在转化的用户装置所必需的 IP 地址。必须通过 API 查询参数进行设置,因为TUNE API 无法提取X-IP-Override Header

device_brand

必要项用户设备的品牌或制造商(例如 “Apple” 或 “Samsung”)

device_model

记录在转化的用户设备的所需的型号(如 “iPhone5,2” 或 “GT-I9300”)

user_agent

必要项设备的用户代理。也可以在网络请求 header 中设置。

os_version

可选用户设备上的操作系统版本(例如 iOS 或 Android)

device_carrier

可选设备的运营商,如果支持蜂窝网络(例如 AT&T)

language

本地设置中设备的可选语言

country_code

可选国家的 ISO ALPHA-2 或 ISO ALPHA-3 值

app_version

用户设备上应用的可选版本(此参数有助于 TUNE 区分新应用安装和现有应用更新)

user_id

可选广告主定义的用户 ID

📘

TUNE API 调用不支持 local_ip

local_ip 被用于 Branch 的 Predictive Modeling 功能,但是不能在 TUNE API 调用中设置。这不会阻止TUNE API endpoint 的归因。