# TalkingData 集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 自定义数据回调 | 回传 | 用户级别 | ✅ | ✅ |
TalkingData 提供了自定义数据回调 (opens new window)功能，我们可以通过该功能获取用户级别的激活或注册数据
在开始接入 TalkingData 移动广告数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 接入 TalkingData 客户端 SDK 与 TE 客户端 SDK，在 TalkingData SDK 中设置 TE 用户识别 ID
- 登录 TE 后台，进入三方集成模块，新增 TalkingData 集成方案，完成相关配置，并复制回调地址
- 登录 TalkingData 后台，在「管理中心」-「数据管理」页面点击「添加数据回调」，选择回调数据的项目以及回调事件（注册或者激活）
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 上报
如果您选择使用客户端 SDK 上报数据，请先在 App 中集成 TalkingData SDK 与 TE SDK。如果您希望回传 TalkingData 的激活事件，接下来通过 TalkingData SDK 初始化时，将 TE SDK 的访客 ID 作为自定义 ID 设置进来：
// 先初始化 TE SDK
TDAnalytics.init(this, APPID, SERVER_URL);
// 获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String distinctId = TDAnalytics.getDistinctId();
// 设置 TalkingData SDK
JLibrary.InitEntry(this); //1.0.13移动安全联盟统一SDK初始化
TalkingDataSDK.init(this, "您的 App ID", "渠道 ID", distinctId);
如果您希望回传注册事件，则可以在 TE SDK 与 TalkingData SDK 中设置同样的账号 ID：
// 获取账号 ID
String accountId = "Account ID";
// 设置 TE SDK
TDAnalytics.login(accountId);
// 设置 TalkingData SDK
TalkingDataSDK.onRegister(accountId);
# 二、方案配置
完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 TalkingData 方案的配置。下图是 TalkingData 自定义数据回调方案的配置界面：
# 2.1 用户识别字段
由于 TalkingData 自定义回调数据是用户级别数据，因此需要为其设置用户识别规则，即 TalkingData SDK 中设置的 TE 系统的用户识别 ID。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：ACCOUNTID
- 访客 ID 关联字段：CUSTOM
# 2.2 事件表入库设置
打开「事件表入库设置」开关后，TalkingData 回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.3 用户属性入库规则
在默认情况下，TE 系统不会将 TalkingData 回传数据写入到用户属性中。如果您希望将一些字段写入用户表，比如用户归因信息字段，请首先打开规则，使其运行，再通过属性映射功能添加需要写入用户表的字段，来源属性名需填写字段的入库名：
我们建议您可以按照以下方式添加需要入库的用户属性：
| 来源数据名 | 目标属性名 | 说明 |
|---|---|---|
| ADNETNAME | te_ads_object.media_source | 媒体渠道 |
| ADCAMPAIGN | te_ads_object.campaign_name | 广告计划名 |
| ADGROUP | te_ads_object.ad_group_name | 广告组名 |
| ADCREATIVE | te_ads_object.ad_name | 广告名 |
# 2.4 集成配置
您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping |
入库后的事件名，可以自定义。Key 为 TalkingData 的回传数据类型，Value 为该事件入库后的事件名。Key 可选：
|
# 2.5 终端地址
若您配置了系统和项目级别数据上报地址，则显示如下链接；您可以直接复制该地址，并粘贴至 TalkingData 后台实时回传配置处：
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到 TalkingData 回传配置页的「终端地址」复制终端地址。
# 三、设置回调
# 3.1 添加数据回调
如果要接入 TalkingData 移动广告数据，您需要登录 TalkingData 移动广告监测后台，在「管理中心」-「数据管理」标签页，可以查看并配置所有的数据回调。
接下来点击「添加数据回调」，即可进入新建数据回调页面
接着，为数据回调取名，选择需要回传数据的应用，并在「回调事件」处选择激活/注册事件中的一个。然后，将 TE 系统中 TalkingData 方案中的终端地址填入「数据接收 URL」处
接下来您需要配置事件参数，请根据您选择的回调事件，结合 3.2 章节内容进行配置。完成配置后点击保存，即可完成回调的配置。
# 3.2 回调参数配置
# 3.2.1 激活事件
如果您回传的是激活事件，我们建议您按照下表中的参数名为每一个宏设置入库名：
| 参数名 | 宏 | 支持平台 | 参数说明 | 样例 |
|---|---|---|---|---|
| APPKEY | #APPKEY | 全平台 | APP在Ad Tracking系统中的唯一标识 | 10691808c7dc494eba8afd44cdef1df7 |
| EVENTTIME | #EVENTTIME | 全平台 | 事件发生时间，13位unix时间戳 | 1451379329000 |
| OSVERSION | #OSVERSION | 全平台 | 设备的系统版本 | 9.2 |
| DEVICETYPE | #DEVICETYPE | 全平台 | 设备的类型 | iPad4,4 |
| OAID | #OAID | Android | Android 设备 ID | |
| OAID_MD5 | #OAID_MD5 | Android | Android 设备加密 ID | |
| OAID_MD5_1 | #OAID_MD5_1 | Android | Android 设备加密 ID | |
| ADVERTISINGID | #ADVERTISINGID | Android | 广告ID，由Google Play Service提供 | 4c30a866-30d6-4418-a6dc-0f702737bf58 |
| ADVERTISINGID_MD5 | #ADVERTISINGID_MD5 | Android | 广告加密 ID | |
| ANDROIDID | #ANDROIDID | Android | Android设备的唯一设备标识号 | |
| ANDROIDID_MD5 | #ANDROIDID_MD5 | Android | Android设备的加密唯一设备标识号 | |
| ANDROIDID_MD5_1 | #ANDROIDID_MD5_1 | Android | Android设备的加密唯一设备标识号 | |
| IMEI | #IMEI | Android | 移动设备国际识别码 | 493002407599521 |
| IMEI2 | #IMEI2 | Android | 移动设备国际识别码2 | |
| TDID | #TDID | 全平台 | TalkingData的唯一设备标识号 | hc5e59e1926ee0fe142b22610cdda14df |
| IP | #IP | 全平台 | 事件发生时的ip | 123.123.123.123 |
| SPREADURL | #SPREADURL | 全平台 | 六位短链，推广活动唯一标识 | Vx7b6c |
| SPREADNAME | #SPREADNAME | 全平台 | 推广活动名称 | “多盟推广-素材1” |
| SPREADGROUP | #SPREADGROUP | 全平台 | 推广活动组名称 | |
| UA | #UA | 全平台 | 点击广告的设备 UA 信息 | |
| CLICKIP | #CLICKIP | 全平台 | 点击广告的设备IP信息 | 123.123.123.123 |
| CLICKTIME | #CLICKTIME | 全平台 | 点击广告的时间，13位unix时间戳 | 1451379329000 |
| ADNETNAME | #ADNETNAME | 全平台 | 广告网络渠道商名称（英文唯一标识） | “Domob” |
| ADNETDESC | #ADNETDESC | 全平台 | 广告网络渠道商描述（中文标识，可能随对接升级进行变更） | “多盟” |
| CHANNELPACKAGEID | #CHANNELPACKAGEID | 全平台 | 应用中集成的分包ID，也称为”channeled” | “jifeng_1” |
| CLICK | @_ | 全平台 | 关联点击的参数json格式表现 | {"a":"1","b":"2"} |
| ASSISTANT_CLICK_1 | #ASSISTANT_CLICK_1 | 全平台 | 助攻点击1的推广活动名称 | |
| ASSISTANT_CLICK_2 | #ASSISTANT_CLICK_2 | 全平台 | 助攻点击2的推广活动名称 | |
| ASSISTANT_CLICK_3 | #ASSISTANT_CLICK_3 | 全平台 | 助攻点击3的推广活动名称 | |
| TD_SUBID | #TD_SUBID | 全平台 | 子渠道 ID | |
| ACTIVE_TYPE | #ACTIVE_TYPE | 全平台 | 激活类型 | |
| FRAUD_PREVENTION | #FRAUD_PREVENTION | IOS Android | 作弊防护标识 | “0”代表无异常； “1”代表IP异常激活； “2”代表时间差转化异常激活； “3”代表关联异常激活； “4”代表IP迁移激活（高级版防作弊特有）； “5”代表LAT异常激活（高级版防作弊特有）； “6”代表全新设备激活（高级版防作弊特有）； |
| ATTRIBUTION_TYPE | #ATTRIBUTION_TYPE | IOS Android | 归因来源 | “click”代表来自点击； “impression”代表来自曝光； “deeplink”代表来自唤醒； |
| ADCREATIVE | #ADCREATIVE | 全平台 | 广告创意 | |
| ADCAMPAIGN | #ADCAMPAIGN | 全平台 | 广告系列 | |
| ADGROUP | #ADGROUP | 全平台 | 广告组 | |
| APPSTOREID | #APPSTOREID | IOS | App Store ID | 1046850159 |
| IDFA | #IDFA | IOS | ios系统下的广告追踪标识符 | 6C59CB5A-3091-4246-AA6E-9C025FE0E33B |
| MAC | #MAC | Android | 符合IEEE 802标准规定的MAC地址字符串 | AB:12:CD:34:EF:56 |
| CUSTOM | #CUSTOM | 全平台 | 自定义参数 | |
| CLICKTRACKID | #CLICKTRACKID | 全平台 | 激活对应的点击的追踪 ID |
# 3.2.2 注册事件
如果您回传的是注册事件，我们建议您按照下表中的参数名为每一个宏设置入库名：
| 参数类名 | 替换宏 | 支持平台 | 参数说明 | 样例 |
|---|---|---|---|---|
| SPREADURL | #SPREADURL | 全平台 | 六位短链，推广活动唯一标识 | Vx7b6c |
| SPREADNAME | #SPREADNAME | 全平台 | 推广活动名称 | “多盟推广-素材1” |
| UA | #UA | 全平台 | 点击广告的设备 UA 信息 | |
| CLICKIP | #CLICKIP | 全平台 | 点击广告的设备IP信息 | 123.123.123.123 |
| CLICKTIME | #CLICKTIME | 全平台 | 点击广告的时间，13位unix时间戳 | 1451379329000 |
| CLICK | @_ | 全平台 | 关联点击的参数json格式表现 | {"a":"1","b":"2"} |
| ACCOUNTID | #ACCOUNTID | 全平台 | 事件发生时应用内的账号 | |
| APPKEY | #APPKEY | 全平台 | APP在Ad Tracking系统中的唯一标识 | 10691808c7dc494eba8afd44cdef1df7 |
| EVENTTIME | #EVENTTIME | 全平台 | 事件发生时间，13位unix时间戳 | 1451379329000 |
| OSVERSION | #OSVERSION | 全平台 | 设备的系统版本 | 9.2 |
| DEVICETYPE | #DEVICETYPE | 全平台 | 设备的类型 | iPad4,4 |
| IDFA | #IDFA | IOS | ios系统下的广告追踪标识符 | 6C59CB5A-3091-4246-AA6E-9C025FE0E33B |
| MAC | #MAC | Android | 符合IEEE 802标准规定的MAC地址字符串 | AB:12:CD:34:EF:56 |
| ADVERTISINGID | #ADVERTISINGID | Android | 广告ID，由Google Play Service提供 | 4c30a866-30d6-4418-a6dc-0f702737bf58 |
| ANDROIDID | #ANDROIDID | Android | Android设备的唯一设备标识号 | |
| IMEI | #IMEI | Android | 移动设备国际识别码 | 493002407599521 |
| TDID | #TDID | 全平台 | TalkingData的唯一设备标识号 | hc5e59e1926ee0fe142b22610cdda14df |
| IP | #IP | 全平台 | 事件发生时的ip | 123.123.123.123 |
| ADNETNAME | #ADNETNAME | 全平台 | 广告网络渠道商名称（英文唯一标识） | “Domob” |
| ADNETDESC | #ADNETDESC | 全平台 | 广告网络渠道商描述（中文标识，可能随对接升级进行变更） | “多盟” |
| CHANNELPACKAGEID | #CHANNELPACKAGEID | 全平台 | 应用中集成的分包ID，也称为”channeled” | “jifeng_1” |
| DEEPLINK | #DEEPLINK | 全平台 | 深度链接 |
# 四、数据入库规则
# 4.1 激活事件入库规则
- 默认情况下使用数据中的 CUSTOM 作为数据中的访客 ID，该字段应可对应 TE 项目中的访客 ID
- 使用数据中的 EVENTTIME 字段，即数据时间，作为事件的 #event_time
- 数据事件名为 -- talkingdata_init_data
- 回调链接中配置的其他字段将全数入库
# 4.2 注册事件入库规则
- 默认情况下使用数据中的 ACCOUNTID 作为数据中的账号 ID，该字段应可对应 TE 项目中的账号 ID
- 使用数据中的 EVENTTIME 字段，即数据时间作为事件的 #event_time
- 数据事件名为 -- talkingdata_register_data
- 回调链接中配置的其他字段将全数入库
# 4.3 标准化字段
TalkingData 回调数据中的部分字段，TE 系统会进行标准化处理：
| 字段 | 标准化字段 | 含义 |
|---|---|---|
| ADCAMPAIGN | te_ads_object.campaign_name | 广告计划名 |
| ADGROUP | te_ads_object.ad_group_name | 广告组名 |
| ADCREATIVE | te_ads_object.ad_name | 广告名 |
| ADNETNAME | te_ads_object.media_source | 媒体渠道 |
| APPSTOREID | te_ads_object.app_id | 应用 ID |
# 五、备注
如果激活事件的 CUSTOM 或注册事件中的 ACCOUNTID 与 TE 项目中的访客 ID、账号 ID 无法对应，则这些事件将挂载在一个虚拟用户身上（访客 ID 为 without_id）。为了将这些挂载在虚拟用户身上的事件数据在之后关联到 TE 项目的实际用户身上，您需要将 TalkingData 的 td_id 设置到相应用户的用户属性中，之后通过数据回溯来实现用户数据的打通。
String td_id = TalkingDataAppCpa.getDeviceId(this);
try {
// 将 td_id 设置为用户属性
JSONObject properties = new JSONObject();
properties.put("td_id",td_id);
TDAnalytics.userSet(properties);
} catch (JSONException e) {
e.printStackTrace();
}