# Branch 集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Webhooks | 回传 | 用户级别 | ✅ | ✅ |
Branch 提供了 Webhooks (opens new window) 回传用户粒度数据，您可以将其中的渠道归因等信息传入 TE 的用户属性，也可以将回传数据写成事件
在开始接入 Branch 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 引入 Branch SDK 与 TE SDK，并在 Branch SDK 设置 TE 系统的访客 ID 和账号 ID
- 登录 TE 后台，进入三方集成模块，新增 Branch Webhook 回传方案，并完成相关配置
- 在 Branch 后台配置 Webhooks，传入 TE 的回调链接
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 上报
如果您选择使用客户端 SDK 上报数据，请先在 App 中集成 Branch SDK 与 TE SDK。接下来通过 Branch SDK 设置 initialization metadata (opens new window) 参数的方法，在 Branch SDK 中设置 TE 系统的用户识别 ID —— 账号 ID 和访客 ID。Branch 的回传数据中将会带有这些 ID 字段，因此可以将 Branch 数据与 TE 数据关联起来。
# 1.1 方案一（自动集成）
- 如果您接入的 Android、iOS SDK
- SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
- SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
- 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案
WARNING
请注意 TE 的 SDK 初始化和开启自动集成代码必须在 Branch 的 SDK 初始化之后立即调用，请按照以下步骤操作：
初始化 TE SDK。
初始化 Branch SDK。
调用
enableThirdPartySharing自动设置访客 ID。
以下各端 SDK 的代码样例：
该方案的原理就是内部自动调用Branch的setRequestMetadata方法，传入 ta_distinct_id 和 ta_account_id。
# 1.2 方案二（手动集成）
手动集成方案，需要您在 Branch SDK 中使用 setRequestMetadata() 接口设置 TE 项目的访客 ID 与账号 ID。
WARNING
请注意 TE SDK初始化需要在 Branch SDK初始化之前完成，并在Branch的SDK初始化后立即开启自动集成代码。请按照以下步骤操作：
初始化 TE SDK。
初始化 Branch SDK。
调用
setRequestMetadata设置访客 ID。
在 Branch 的 Webhook 回传数据中，ta_distinct_id和ta_account_id即对应 TE 系统的访客 ID 和账号 ID。
TIP
请在 Branch SDK 初始化完毕后立刻调用 setRequestMetadata() 设置 metadata 参数，避免部分 Branch 数据中缺少 metadata 参数。如果仍然出现数据中不包含 metadata 参数的情况，或者用户识别字段无法在初始化后立即获取，可以通过 Branch 提供的 Delay Session Initialization 方法 (opens new window) 来延迟 session 初始化，在延迟期间完成 metadata 的设置，来确保数据中都带有用户识别字段。
# 二、方案配置
完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 Branch 的配置。下图是 Branch 的配置界面：
# 2.1 用户识别字段
由于 Branch Webhook 数据是用户级别数据，因此需要为其设置用户识别规则，即 Branch SDK 中设置的 TE 系统的用户识别 ID。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：ta_account_id
- 访客 ID 关联字段：ta_distinct_id
# 2.2 事件表入库设置
打开「事件表入库设置」开关后，Branch 回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.3 用户属性入库规则
在默认情况下，TE 系统会自动将 Branch 回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| Adjust 字段 | 入库 TA 后用户属性名称 | 说明 |
|---|---|---|
| query.channel | te_ads_object.media_source | 渠道 |
| query.campaign | te_ads_object.campaign_name | 广告计划 |
| query.ad_set_name | te_ads_object.ad_group_name | 广告组 |
| query.creative_name | te_ads_object.ad_name | 广告素材 |
如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示
您可以修改用户属性的入库方式，默认是 user_setOnce，也就是只会保留首次上报的信息。
来源属性名请在入库字段名前加入query.前缀
您可以点击「属性映射」按钮添加需要写入用户属性的字段；也可以点击左侧的「规则」按钮增添一套新的规则。
如果您希望关闭用户属性入库，可以停止所有规则：
# 2.4 集成配置
您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义。Key 为 Branch 回传数据的事件名，Value 为该事件入库后的事件名 |
# 2.5 终端地址
若您配置了系统和项目级别数据上报地址，则显示如下链接
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到 Branch Webhook 配置页的「终端地址」复制终端地址。
# 2.5.2 自定义宏
Branch Webhook 的回调地址中包含一种称为宏的结构，表示方法为${(宏名称)!}。宏可以被认为是一种占位符，当 Branch 需要回传的数据中包含与宏对应的字段。以 ${(last_attributed_touch_data.~campaign)!}为例， Branch 会在回传数据时，将 Campaign 的值填入回调地址中宏所在位置。
请将您刚刚获取的终端地址，替换以下地址中的开头部分，请将替换后的回调地址复制下来，之后在 Branch 后台中需要填入该地址：
https://{终端地址}?branch_id=${(id)!}&campaign=${(last_attributed_touch_data.~campaign)!}&campaign_id=${(last_attributed_touch_data.~campaign_id)!}&campaign_type=${(last_attributed_touch_data.~campaign_type)!}&customer_campaign=${(last_attributed_touch_data.~customer_campaign)!}&channel=${(last_attributed_touch_data.~channel)!}&feature=${(last_attributed_touch_data.~feature)!}&stage=${(last_attributed_touch_data.~stage)!}&tags=${(last_attributed_touch_data.~tags)!}&advertising_partner_name=${(last_attributed_touch_data.~advertising_partner_name)!}&advertising_partner_id=${(last_attributed_touch_data.~advertising_partner_id)!}&secondary_publisher=${(last_attributed_touch_data.~secondary_publisher)!}&secondary_publisher_id=${(last_attributed_touch_data.~secondary_publisher_id)!}&customer_secondary_publisher=${(last_attributed_touch_data.~customer_secondary_publisher)!}&creative_name=${(last_attributed_touch_data.~creative_name)!}&creative_id=${(last_attributed_touch_data.~creative_id)!}&ad_set_name=${(last_attributed_touch_data.~ad_set_name)!}&ad_set_id=${(last_attributed_touch_data.~ad_set_id)!}&customer_ad_set_name=${(last_attributed_touch_data.~customer_ad_set_name)!}&ad_name=${(last_attributed_touch_data.~ad_name)!}&ad_id=${(last_attributed_touch_data.~ad_id)!}&customer_ad_name=${(last_attributed_touch_data.~customer_ad_name)!}&keyword=${(last_attributed_touch_data.~keyword)!}&keyword_id=${(last_attributed_touch_data.~keyword_id)!}&customer_keyword=${(last_attributed_touch_data.~customer_keyword)!}&branch_ad_format=${(last_attributed_touch_data.~branch_ad_format)!}&technology_partner=${(last_attributed_touch_data.~technology_partner)!}&banner_dimensions=${(last_attributed_touch_data.~banner_dimensions)!}&placement=${(last_attributed_touch_data.~placement)!}&placement_id=${(last_attributed_touch_data.~placement_id)!}&customer_placement=${(last_attributed_touch_data.~customer_placement)!}&sub_site_name=${(last_attributed_touch_data.~sub_site_name)!}&customer_sub_site_name=${(last_attributed_touch_data.~customer_sub_site_name)!}&agency=${(last_attributed_touch_data.~agency)!}&agency_id=${(last_attributed_touch_data.~agency_id)!}&ta_distinct_id=${(custom_data.ta_distinct_id)!}&ta_account_id=${(custom_data.ta_account_id)!}
# 2.6 保存方案
完成配置后，请您点击右上角的保存按钮，将该方案保存下来。
# 三、配置 Branch Webhook 回调
完成方案保存后，请您登录 Branch 后台，进入「Data Feeds」页，在「WEBHOOKS」标签页中添加新的 Webhook：
配置 Webhook 链接和详情，从上到下，从左到右共需要填写三部分内容：
- 「Send a webhook to」：将您在 TE 后台获取的终端地址加上所需的自定义宏后，填写在此处
- 「using a ...」：选择 POST 方法
- 「every time users trigger the event ...」：如果使用客户端 SDK 上报，可以选择 INSTALL 事件
点击「Save Rule」保存规则，即完成了 Branch 回调的配置
TIP
iOS 14.5 后的 install 激活事件说明：
当激活归因于付费广告时，第二个 install 激活事件将在用户选择 opt-in ATT 后触发 选择 opt-in 将影响您的最终激活数的统计。我们的建议是使用不同的标识符（例如 IDFV）来在内部系统上删除重复的激活事件（可在 TE 系统内使用二次开发工具的进行）。
# 四、数据入库
# 4.1 事件入库规则
- 使用数据中的 event_timestamp 字段，作为事件的 #event_time
- 数据的事件名取集成配置中的 source.event_mapping，默认情况下为：
- 安装：branch_install
- 其他没有写在 source.event_mapping 中的事件：在 name 字段前加
branch_前缀
- 其他回调地址中的宏对应的属性将全数入库
以下是您使用本文档提供的回调地址后，Branch 将会回传的属性列表：
| 入库名 | 含义 |
|---|---|
| name | Branch 事件名 |
| event_timestamp | 数据时间 |
| campaign | 归因 Campaign 名 |
| campaign_id | 归因 Campaign ID |
| campaign_type | 归因 Campaign 类型（取自 Google AAP归因） |
| customer_campaign | 自定义归因 Campaign 名 |
| channel | 归因 Channel 名 |
| feature | 归因 Feature，取值如"paid advertising" |
| stage | Stage |
| tags | 归因标签 |
| advertising_partner_name | 可读的 Advertising Partner 名 |
| advertising_partner_id | Advertising Partner ID |
| secondary_publisher | Secondary Publisher 名 |
| secondary_publisher_id | Secondary Publisher ID |
| customer_secondary_publisher | 自定义 Secondary Publisher ID |
| creative_name | 归因 Creative 名 |
| creative_id | 归因 Creative ID |
| ad_set_name | 归因 Ad Set 名 |
| ad_set_id | 归因 Ad Set ID |
| customer_ad_set_name | 自定义 Ad Set 名 |
| ad_name | 归因 Ad 名 |
| ad_id | 归因 Ad ID |
| customer_ad_name | 自定义 Ad 名 |
| keyword | 归因 Keyword |
| keyword_id | 归因 Keyword ID |
| customer_keyword | 自定义 Keyword |
| branch_ad_format | 广告类型，取值如 Search, Display, Product Ad, App only |
| technology_partner | 第三方 Technology Partner |
| banner_dimensions | Banner 尺寸 |
| placement | 归因 Placement |
| placement_id | 归因 Placement ID |
| customer_placement | 自定义 Placement |
| sub_site_name | Sub Site 名 |
| customer_sub_site_name | 自定义 Sub Site 名 |
| agency | Agency 名 |
| agency_id | Agency ID |
| ta_distinct_id | TE 系统的访客 ID |
| ta_account_id | TE 系统的账号 ID |
# 4.2 标准化字段
Branch Webhook 回调数据报告中的部分字段，TE 系统会进行标准化处理
| 原字段 | 标准化字段 | 含义 |
|---|---|---|
| campaign | te_ads_object.campaign_name | 广告计划名 |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| ad_set_name | te_ads_object.ad_group_name | 广告组名，变现广告的 Unit 名 |
| ad_set_id | te_ads_object.ad_group_id | 广告组 ID，变现广告的 Unit ID |
| ad_name | te_ads_object.ad_name | 广告名 |
| ad_id | te_ads_object.ad_id | 广告 ID |
| placement | te_ads_object.placement | 广告位置 |
| channel | te_ads_object.media_source | 媒体渠道 |