# AppsFlyer Pull Raw Data
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Pull API Raw Data | API | 用户级别 | ✅ | ✅ | ✅ |
Pull API Raw Data (opens new window) 可以拉取一段时间内的用户级别数据，这种集成方式即可以在不要求实时性的情况下获取用户明细数据，也非常适合拉取用户粒度的历史数据。
# 集成流程
- 接入 AppsFlyer 客户端 SDK (opens new window) 与 TE SDK，并在 AF SDK 中设置 TE 的用户识别 ID
- 登录 AppsFlyer 后台，获取 V2.0 API Token 与 App ID
- 登录 TE 后台，进入三方集成模块，新增 AppsFlyer Pull Raw Data 方案，并完成相关配置
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
集成 AppsFlyer 数据的第一步，是在客户端完成 TE SDK 与 AF SDK 的打通，在 AF SDK 中设置 TE 系统的用户识别 ID
# 1.1 方案一（自动集成）
- 如果您接入的 TE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
- 如果您接入的 TE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
// 初始化 TE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// 开启 AppsFlyer id关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);
// 初始化 AppsFlyer SDK
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);
// 强烈建议您使用 setcustomerUserId() 再设置一遍访客 ID
String distinctId = ThinkingAnalyticsAPI.GetDistinctId();
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);
// 在调用 login 设置账号 ID 后需要再次同步数据（可选）
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);
如果调用了 TE SDK 的 login() 方法或者 identify() 方法，需要再次调用 enableThirdPartySharing() 同步数据。
注意：如果您也需要调用 AppsFlyer SDK 的 setAdditionalData() 方法，由于该方法调用多次，会覆盖之前的参数，因此可以将参数传递给 TE SDK，TE SDK 内部会将参数进行拼接合并。
Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
instance.enableThirdPartySharing(
TDThirdPartyShareType.TD_APPS_FLYER,
additionalData
);
本方案的原理就是内部自动调用 AppsFlyer 的 setAdditionalData() 方法，传入 TE 项目的访客 ID 与账号 ID。
# 1.2 方案二（手动集成）
手动集成方案，需要您在 AppsFlyer SDK 中使用 setAdditionalData 配置 TE 项目的访客 ID 与账号 ID， 以下是 Java 的代码样例：
// 获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String distinctId = ThinkingAnalyticsAPI.GetDistinctId();
// 您的账号 ID (或 角色 ID)，对应 TE 中的 #account_id
String accountId = "your_account_id";
// 激活时部署
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);
// 强烈建议您使用 setcustomerUserId() 再设置一遍访客 ID
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);
...
// 注册时部署
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id", distinctId);
CustomDataMap.put("ta_account_id",accountId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);
经过以上设置后，回传数据中的custom_data 将带有 ta_distinct_id、ta_account_id 这两个字段，customer_user_id 则等于访客 ID。
# 二、获取 API Token 与 App ID
# 2.1 获取 API Token
请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Pull API Raw Data 的 V2.0 API Token。
# 2.2 获取 App ID
可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678 
# 三、方案配置
获取完 AppsFlyer 的 API Token 与 App ID 之后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 AppsFlyer Pull Raw Data 的配置界面，请您按照本章节内容完成方案的创建：
# 3.1 授权信息配置
点击「授权信息」按钮，在弹出框内填写 API Token 与 App ID
# 3.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 AppsFlyer Pull Raw Data 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 3.3 拉取时区
您还可以设置拉取的数据的时区，默认为 UTC+0
# 3.4 用户识别字段
由于 AppsFlyer Pull Raw Data 回传的是用户级别数据，因此需要为其设置用户识别规则，即 AF 回传数据与#distinct_id 和 #account_id 对应的字段。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：custom_data.ta_account_id
- 访客 ID 关联字段：customer_user_id,custom_data.ta_distinct_id
# 3.5 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
# 3.6 用户属性入库规则
在默认情况下，TE 系统会自动将 AF 回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：
| AppsFlyer 字段 | 标准化字段 | 说明 |
|---|---|---|
| media_source | te_ads_object.media_source | 媒体渠道 |
| campaign | te_ads_object.campaign_name | 广告计划名 |
| adset | te_ads_object.ad_group_name | 广告组名 |
| ad | te_ads_object.ad_name | 广告名 |
如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示：
您可以点击「属性映射」按钮添加需要写入用户属性的字段；也可以点击左侧的「规则」按钮增添一套新的规则，比如您希望从 AF 回传的变现数据中提取广告收益，并将其以 user_add 的方式写入到用户属性中，从而记录各用户的累计广告收益。
如果您希望关闭用户属性入库，可以停止所有规则：
# 3.7 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的类型，拉取的维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义 |
| source | report_types | 拉取的数据类型，可以自定义，默认为 installs、ad_revenue，即安装与变现事件 |
| group_by | 数据中的分组维度，列表类型，可以自定义 | |
| extra_params | double_columns | 数值类型字段定义，写在此处的字段将会以数值类型入库，需填写入库后的字段名 |
默认情况下 Pull API Raw Data 支持拉取以下数据：
您也可以查看 AppsFlyer 官网文档 (opens new window)获取更多支持的字段，您可以将需要的字段填写在 source.group_by 中
# 3.7.1 默认涵盖指标
| 字段 | 中文名 |
|---|---|
| event_value | 事件值 |
| event_revenue | 事件收益 |
| event_revenue_usd | 事件收益（USD） |
| cost_value | 成本值 |
# 3.7.2 默认维度字段
| 字段 | 中文名 |
|---|---|
| attributed_touch_time | 归因时间 |
| install_time | 激活时间 |
| event_time | 事件时间 |
| event_name | 事件名称 |
| event_value | 事件值 |
| event_revenue | 事件收益 |
| event_revenue_currency | 事件收益货币类型 |
| event_revenue_usd | 事件收益（USD） |
| event_source | 事件来源 |
| is_receipt_validated | 是否开启验证接收 |
| partner | 合作伙伴 |
| media_source | 媒体渠道 |
| channel | 子渠道 |
| keywords | 关键词 |
| campaign | 广告计划名称 |
| campaign_id | 广告计划 ID |
| adset | 广告组名称 |
| adset_id | 广告组 ID |
| ad | 广告素材名称 |
| ad_id | 广告素材 ID |
| ad_type | 广告类型 |
| site_id | 站点 ID |
| sub_site_id | 子站点 ID |
| sub_param_1 | 子参数 1 |
| sub_param_2 | 子参数 2 |
| sub_param_3 | 子参数 3 |
| sub_param_4 | 子参数 4 |
| sub_param_5 | 子参数 5 |
| cost_model | 成本模型 (CPC/CPI/CPM/Other) |
| cost_value | 成本值 |
| cost_currency | 成本货币类型 |
| contributor_1_partner | 贡献者 1 合作伙伴 |
| contributor_1_media_source | 贡献者 1 媒体渠道 |
| contributor_1_campaign | 贡献者 1 广告计划 |
| contributor_1_touch_type | 贡献者 1 归因类型 |
| contributor_1_touch_time | 贡献者 1 归因时间 |
| contributor_2_partner | 贡献者 2 合作伙伴 |
| contributor_2_media_source | 贡献者 2 媒体渠道 |
| contributor_2_campaign | 贡献者 2 广告计划 |
| contributor_2_touch_type | 贡献者 2 归因类型 |
| contributor_2_touch_time | 贡献者 2 归因时间 |
| contributor_3_partner | 贡献者 3 合作伙伴 |
| contributor_3_media_source | 贡献者 3 媒体渠道 |
| contributor_3_campaign | 贡献者 3 广告计划 |
| contributor_3_touch_type | 贡献者 3 归因类型 |
| contributor_3_touch_time | 贡献者 3 归因时间 |
| region | 地区 |
| country_code | 国家代码 |
| state | 州/省 |
| city | 城市 |
| postal_code | 邮政编码 |
| dma | DMA码 |
| ip | IP地址 |
| wifi | 是否开启WI-FI |
| operator | 移动运营商 |
| carrier | 手机运营商 |
| language | 语言 |
| appsflyer_id | AppsFlyer ID |
| advertising_id | Advertising ID |
| idfa | IDFA |
| android_id | Android ID |
| customer_user_id | Customer User ID |
| imei | IMEI |
| idfv | IDFV |
| platform | 平台 |
| device_type | 设备类型 |
| os_version | 操作系统 |
| app_version | 应用版本 |
| sdk_version | SDK 版本 |
| app_id | App ID |
| app_name | 应用名称 |
| bundle_id | Bundle ID |
| is_retargeting | 是否再营销 |
| retargeting_conversion_type | 再营销转化类型 |
| attribution_lookback | 归因 Lookback |
| reengagement_window | 再互动窗口 |
| is_primary_attribution | 是主归因 |
| user_agent | 用户代理 |
| http_referrer | HTTP Referrer |
| original_url | 原始 URL |
# 3.7.3 默认配置中增加的额外字段
这部分内容可以在集成配置的 source.group_by 中进行调整
| 字段 | 中文名 |
|---|---|
| device_model | 机型 |
| keyword_id | AF 的 关键字 ID |
| store_reinstall | 重新安装时的应用市场 |
| deeplink_url | Deeplink 地址 |
| oaid | OAID |
| install_app_store | 安装时的应用商城 |
| contributor1_match_type | 贡献者 1 匹配模式 |
| contributor2_match_type | 贡献者 2 匹配模式 |
| contributor3_match_type | 贡献者 3 匹配模式 |
| match_type | 归因匹配模式 |
| device_category | 设备大类：手机、笔记本、其他 |
| gp_referrer | Google Play 的 URL referrer |
| gp_click_time | Google Play 记录的广告点击时间 |
| gp_install_begin | Google Play 记录的安装时间 |
| amazon_aid | Amazon 设备 ID |
| keyword_match_type | 关键字匹配模式 |
| att | iOS 14+ 的 ATT 状态 |
| conversion_type | 转换类型 |
| campaign_type | 广告计划类型 |
| is_lat | 用户是否限制数据跟踪，为真时，IDFA 或 GAID 会被替换为全0 |
| custom_data | Customer Data，用来获取用户识别字段 |
# 3.8 数据入库规则
Pull Raw Data 数据接口会入库多种数据，每种数据的处理规则如下：
- Installs 数据
- 拉取仅包含 user acquisition（UA）的 Installs (opens new window) 数据以及 Organic Installs (opens new window) 数据
- 数据以事件形式写入，事件名为 af_install
- 以数据中的 event_time，即事件发生时刻，作为事件的 #event_time
- 默认的用户属性入库规则，会将 Installs 数据中部分字段写入用户表
- 以用户识别字段配置来确定用户识别字段，如果没有配置用户识别规则，默认取数据中的 customer_user_id 作为访客 ID。没有获取到用户识别字段，则该条数据将会被抛弃。
- 所有字段均会入库，double_column 中的字段以数据类型入库，其他字段以字符串入库
- Ad Revenue
- 拉取 Attributed ad revenue (opens new window)、Organic ad revenue (opens new window)，其中 Attributed ad revenue (opens new window) 会同时拉取 user acquisition（UA）和 retargeting 数据
- 数据将以事件形式写入，事件名为 af_ad_revenue_raw
- 以数据中的 event_time，即事件发生时刻，作为事件的 #event_time
- 以用户识别字段配置来确定用户识别字段，如果没有配置用户识别规则，默认取数据中的 customer_user_id 作为访客 ID。没有获取到用户识别字段，则该条数据将会被抛弃。
- 所有字段均会入库，double_column 中的字段以数据类型入库，其他字段以字符串入库
# 3.9 标准化字段
以下事件属性会进行标准化处理：
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| media_source | te_ads_object.media_source | 媒体渠道 |
| monetization_network（广告变现数据） | te_ads_object.media_source | 变现渠道 |
| campaign | te_ads_object.campaign_name | 广告计划名 |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| adset | te_ads_object.ad_group_name | 广告组名 |
| ad_unit（广告变现数据） | te_ads_object.ad_group_name | 变现广告的 Unit 名 |
| adset_id | te_ads_object.ad_group_id | 广告组 ID |
| ad | te_ads_object.ad_name | 广告名 |
| ad_id | te_ads_object.ad_id | 广告 ID |
| segment（广告变现数据） | te_ads_object.placement | 广告位置 |
| cost_value | te_ads_object.cost | 投放成本 |
| af_cost_currency | te_ads_object.currency | 买量投放的币种 |
| event_revenue | te_ads_object.revenue | 变现收益 |
| event_revenue_currency（广告变现数据） | te_ads_object.currency | 变现收益的币种 |
| country_code | te_ads_object.country | 国家地区编码 |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| app_id | te_ads_object.app_id | 应用 ID |
| app_name | te_ads_object.app_name | 应用名 |