归因 API

概述

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,可从实时环境的操作后台帐户设置中获得 key_live_example
branch_secret String 必需项 您的实时 API Secret,可从实时环境的操作后台帐户设置中获得 secret_live_example
server_to_server Boolean 必需项 始终设置为 true 真正
app_version String 必需项 您的 App 版本 "1.12.4"
操作系统 String 必需项仅接受 AndroidiOS “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 必需项在 iOS 中,填充 IDFA(如果可用) ,否则回退到 IDFV 。在 Android 上,填充 ANDROID_ID(硬件 ID)如果没有可用的设备 ID,则不要包含在请求中

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

Android: "fae098e4605e79c3"

hardware_id_type String 必需项 — 仅适用于 iOS值用于确认 hardware_id 属性中的 iOS ID 是 “idfa” 还是 “vendor_id”(如果没有 hardware_id,则不需要将其包含在请求中 "idfa" or "vendor_id"
ios_vendor_id String 必需项 — 仅适用于 iOS 如果有,则为 IDFV否则不用包含在请求中 "0C381C08-B808-4C25-BE51-B00BC165B5F8"
google_advertising_id String 必需项 — 仅限 ANDROID 如果有,则为 Google 广告 ID否则不用包含在请求中 "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 必需项 如果无法填充 hardware_id 属性,设置为 false,否则默认为 true 真正
ad_tracking_enabled Boolean 必需项 用于确定 IDFA 或 GAID 是否可用于广告目的的值。如果应启用“Limit Ad Tracking(限制广告追踪)”,则不要包含在请求中。 真正
local_ip String 如果可用,这是设备的本地 IP 地址。这是所需 IP header 的增量。可选的但强烈推荐的数据元数据,可提高归因准确性。 “192.168.1.153”
screen_height 整数 设备屏幕的高度。可选的但有用的数据元数据,可提高归因准确性。 2208
screen_width 整数 设备屏幕的宽度。可选的但有用的数据元数据,可提高归因准确性。 1242
link_identifier String URI 打开 App 时,检查 link_click_id 查询项,并使用该值填充(如果缺少,则不要包含在请求中
link_click_id 也可能来自 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 以确保我们从 Facebook 的延迟深度链接 API 中获得深度链接(要求将您的Facebook App Secret 添加到 Branch 操作后台 真正
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 来自 Google Install Referrer 上 ReferrerUrl 的 google_search_install_referrer 查询参数的值。仅在 App 的第一个会话中包含(如果可用) “7AXhuEQs1U”
clicked_referrer_ts Long 仅 ANDROID Play Install Referrer library 收集的引荐来源点击时间戳。
仅在 App 的第一个会话中包含(如果可用)
1573098834
install_begin_ts Long 仅 ANDROIDPlay Install Referrer library 收集的安装开始时间戳记。仅在 App 的第一个会话中包含(如果可用) 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 来自 Apple Search Ads API整个 请求结果的 Base64 encoded string。仅在 App 的第一个会话中包含(如果可用) "eyJWZXJzaW9uMy4xIjp7ImlhZC1wdXJjaGFzZS1kYXRlIjoiMjAyMC0wNi0yOVQxODo1MDoxNloiLCJpYWQta2V5d29yZCI6IktleXdvcmQiLCJpYWQtYWRncm91cC..."
first_session Boolean 标识这是否是用户第一次打开应用。如果为true ,则 Branch 将检查我们是否看到用户以前下载了该应用,如果是,则将会话标记为重新安装,如果不是,则标记为安装。如果此值设置为false ,则 Branch 将把会话计为打开。 真正
server_to_server_identity Boolean 设置为 true 可以在 v1/open 请求中设置 randomized_bundle_token 属性,并在请求结果中返回一个值。如果不使用此功能,请不要在请求中设置此属性。 false
randomized_bundle_token Boolean 如果 server_to_server_identitytrue ,则 Branch 在任何未设置 randomized_bundle_token 请求中返回新的标识值。在第一个请求之后,必须使用在第一个平台请求结果中收到的 randomized_bundle_token 将属性进行 hardcode。无法在后续请求中返回此值严重限制了该用户连接不同事件的能力。 “791040498773585647”
身份 String 如果 server_to_server_identitytrue ,则此属性可将自定义用户 ID 与 Branch 的匿名身份相关联。您绝不应在此处使用个人用户信息,所有值都应先加密再传给 Branch。 “U1923847128356”
tracking_disabled Boolean 如果设置为true ,则 Branch 将不会存储此应用会话中的任何数据。平台请求结果仍然可以返回深度链接数据进行处理,但是此后将不存储任何信息。 false
disable_ad_network_callouts Boolean 如果设置为 true ,则可以使用 Branch 操作后台 (Dashboard) 有选择地删除带有此标记的会话,不会将此类会话发送至广告平台 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 —这将告诉您当前的应用会话是否是通过 Branch 深度链接获得的。可以将其用作条件触发器,指示是否使用特定于 Branch 的逻辑或其他深度链接路由逻辑。
  • +non_branch_link —如果非 Branch 深度链接打开了您的应用(即 Univeral Link),则可以从此 key 中获得该链接
  • +is_first_session —如果 Branch 之前从未见过该用户的设备安装该应用,则为 TRUE
  • +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 —这将包含可用于深度链接路由的 url。如果您的应用已经设置为路由 Universal Links 或 Android App Links,则可以将此值传递到该预先存在的路由逻辑中。
  • $deeplink_path —这将包含可用于深度链接路由的 URI 相对路径。如果您的应用已经设置为导离 URI Schemes,则可以将此值传递到该预先存在的路由逻辑中。

自然请求结果示例

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

配置更新

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

  • Retrieve the device ID (IDFA or IDFV) when available
  • 获得设备的公共 IP
  • 获得设备的 User-Agent
  • 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)
  • 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:

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

配置更新

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

  • Retrieve the device ID (GAID or Android_ID when available
  • 获得设备的公共 IP
  • 获得设备的 User-Agent
  • 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)
  • 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 会话期间发生

  • Upon app launch, query the Google Play Install Referrer library for the referrer Url, click timestamp, and install timestamp
  • 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.
  • 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 的归因。


这个页面对您有帮助吗?