跳到主要内容

AppsFlyer Pull Raw Data

最近更新 2026/10/03
提示

请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量

概要​

接口简介​

接口名类型粒度归因成本收益展示点击转化
Pull API Raw DataAPI用户级别✅✅✅

Pull API Raw Data 可以拉取一段时间内的用户级别数据，这种集成方式既可以在不要求实时性的情况下获取用户明细数据，也非常适合拉取用户粒度的历史数据。

集成流程​

  1. 接入 AppsFlyer 客户端 SDK 与 AE SDK，并在 AF SDK 中设置 AE 的用户识别 ID
  2. 登录 AppsFlyer 后台，获取 V2.0 API Token 与 App ID
  3. 登录 AE 后台，进入三方集成模块，新增 AppsFlyer Pull Raw Data 方案，并完成相关配置
  4. 查看 AE 系统是否成功接收数据，并完成报表搭建

一、客户端 SDK 配置​

集成 AppsFlyer 数据的第一步，是在客户端完成 AE SDK 与 AF SDK 的打通，在 AF SDK 中设置 AE 系统的用户识别 ID

1.1 方案一（自动集成）​

  • 如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
  • 如果您接入的 AE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 三方数据 与 iOS SDK 三方数据
// 初始化 AE SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);

// 开启 AppsFlyer id关联
TDAnalytics.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

// 初始化 AppsFlyer SDK
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);

// 强烈建议您使用 setcustomerUserId() 再设置一遍访客 ID
String distinctId = TDAnalytics.GetDistinctId();
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);

// 在调用 login 设置账号 ID 后需要再次同步数据（可选）
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

如果调用了 AE SDK 的 login() 方法或者 identify() 方法，需要再次调用 enableThirdPartySharing() 同步数据。

注意：如果您也需要调用 AppsFlyer SDK 的 setAdditionalData() 方法，由于该方法调用多次，会覆盖之前的参数，因此可以将参数传递给 AE SDK，AE SDK 内部会将参数进行拼接合并。

Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
TDAnalytics.enableThirdPartySharing(
    TDThirdPartyShareType.TD_APPS_FLYER,
    additionalData
);

本方案的原理就是内部自动调用 AppsFlyer 的 setAdditionalData() 方法，传入 AE 项目的访客 ID 与账号 ID。

1.2 方案二（手动集成）​

手动集成方案，需要您在 AppsFlyer SDK 中使用 setAdditionalData 配置 AE 项目的访客 ID 与账号 ID， 以下是 Java 的代码样例：

// 获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String distinctId = TDAnalytics.GetDistinctId();
// 您的账号 ID (或 角色 ID)，对应 AE 中的 #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 之后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 AppsFlyer Pull Raw Data 的配置界面，请您按照本章节内容完成方案的创建：

3.1 授权信息配置​

点击「授权信息」下的「配置授权信息」按钮，在弹出框内填写 API Token 与 App ID

3.2 定时拉取​

您可以在「定时拉取」模块设置 AE 系统定时拉取 AppsFlyer Pull Raw Data 数据的策略，可以选择在每天的某时拉取一段时间的数据，单次最多拉取 31 天。由于拉取的数据也会计入数据量，建议不要定时拉取太长时间的数据

3.3 拉取时区​

您还可以设置拉取的数据的时区，默认为 UTC+0

3.4 用户识别字段​

由于 AppsFlyer Pull Raw Data 回传的是用户级别数据，因此需要为其设置用户识别规则，即 AF 回传数据与#distinct_id 和 #account_id 对应的字段。AE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。

如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：

  • 账号 ID 关联字段：custom_data.ta_account_id
  • 访客 ID 关联字段：customer_user_id,custom_data.ta_distinct_id

3.5 入库设置​

您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。

3.6 用户属性入库规则​

在默认情况下，AE 系统会自动将 AF 回传数据中的归因字段写入到标准化处理后的用户属性中，以下是写入用户属性的字段及其含义：

AppsFlyer 字段标准化字段说明
media_sourcete_ads_object.media_source媒体渠道
campaignte_ads_object.campaign_name广告计划名
adsette_ads_object.ad_group_name广告组名
adte_ads_object.ad_name广告名
提示

旧版本的用户属性入库默认规则与当前不一致，请注意分辨。如果需要将新老属性合并，可以使用虚拟属性功能

如果需要进行修改，您可以点击「配置规则」进入到入库规则配置页，如下图所示：

您可以点击「属性映射」按钮添加需要写入用户属性的字段；也可以点击左侧的「规则」按钮增添一套新的规则，比如您希望从 AF 回传的变现数据中提取广告收益，并将其以 user_add 的方式写入到用户属性中，从而记录各用户的累计广告收益。

如果您希望关闭用户属性入库，可以停止所有规则：

3.7 集成配置​

最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的类型，拉取的维度，以及入库后的事件名等。

集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：

模块名称含义
sink_eventevent_mapping入库后的事件名，可以自定义
sourcereport_types拉取的数据类型，可以自定义，默认为 installs、ad_revenue，即安装与变现事件
group_by数据中的分组维度，列表类型，可以自定义
extra_paramsdouble_columns数值类型字段定义，写在此处的字段将会以数值类型入库，需填写入库后的字段名

默认情况下 Pull API Raw Data 支持拉取以下数据：

您也可以查看 AppsFlyer 官网文档获取更多支持的字段，您可以将需要的字段填写在 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邮政编码
dmaDMA码
ipIP地址
wifi是否开启WI-FI
operator移动运营商
carrier手机运营商
language语言
appsflyer_idAppsFlyer ID
advertising_idAdvertising ID
idfaIDFA
android_idAndroid ID
customer_user_idCustomer User ID
imeiIMEI
idfvIDFV
platform平台
device_type设备类型
os_version操作系统
app_version应用版本
sdk_versionSDK 版本
app_idApp ID
app_name应用名称
bundle_idBundle ID
is_retargeting是否再营销
retargeting_conversion_type再营销转化类型
attribution_lookback归因 Lookback
reengagement_window再互动窗口
is_primary_attribution是主归因
user_agent用户代理
http_referrerHTTP Referrer
original_url原始 URL

3.7.3 默认配置中增加的额外字段​

这部分内容可以在集成配置的 source.group_by 中进行调整

字段中文名
device_model机型
keyword_idAF 的 关键字 ID
store_reinstall重新安装时的应用市场
deeplink_urlDeeplink 地址
oaidOAID
install_app_store安装时的应用商城
contributor1_match_type贡献者 1 匹配模式
contributor2_match_type贡献者 2 匹配模式
contributor3_match_type贡献者 3 匹配模式
match_type归因匹配模式
device_category设备大类：手机、笔记本、其他
gp_referrerGoogle Play 的 URL referrer
gp_click_timeGoogle Play 记录的广告点击时间
gp_install_beginGoogle Play 记录的安装时间
amazon_aidAmazon 设备 ID
keyword_match_type关键字匹配模式
attiOS 14+ 的 ATT 状态
conversion_type转换类型
campaign_type广告计划类型
is_lat用户是否限制数据跟踪，为真时，IDFA 或 GAID 会被替换为全0
custom_dataCustom Data，用来获取用户识别字段

3.8 数据入库规则​

Pull Raw Data 数据接口会入库多种数据，每种数据的处理规则如下：

  • Installs 数据

    • 拉取仅包含 user acquisition（UA）的 Installs 数据以及 Organic Installs 数据
    • 数据以事件形式写入，事件名为 af_install
    • 以数据中的 event_time，即事件发生时刻，作为事件的 #event_time
    • 默认的用户属性入库规则，会将 Installs 数据中部分字段写入用户表
    • 以用户识别字段配置来确定用户识别字段，如果没有配置用户识别规则，默认取数据中的 customer_user_id 作为访客 ID。没有获取到用户识别字段，则该条数据将会被抛弃。
    • 所有字段均会入库，double_columns 中的字段以数值类型入库，其他字段以字符串入库

  • Ad Revenue

    • 拉取 Attributed ad revenue、Organic ad revenue，其中 Attributed ad revenue 会同时拉取 user acquisition（UA）和 retargeting 数据
    • 数据将以事件形式写入，事件名为 af_ad_revenue_raw
    • 以数据中的 event_time，即事件发生时刻，作为事件的 #event_time
    • 以用户识别字段配置来确定用户识别字段，如果没有配置用户识别规则，默认取数据中的 customer_user_id 作为访客 ID。没有获取到用户识别字段，则该条数据将会被抛弃。
    • 所有字段均会入库，double_columns 中的字段以数值类型入库，其他字段以字符串入库

3.9 标准化字段​

以下事件属性会进行标准化处理：

原始字段标准化字段含义
media_sourcete_ads_object.media_source媒体渠道
monetization_network（广告变现数据）te_ads_object.media_source变现渠道
campaignte_ads_object.campaign_name广告计划名
campaign_idte_ads_object.campaign_id广告计划 ID
adsette_ads_object.ad_group_name广告组名
ad_unit（广告变现数据）te_ads_object.ad_group_name变现广告的 Unit 名
adset_idte_ads_object.ad_group_id广告组 ID
adte_ads_object.ad_name广告名
ad_idte_ads_object.ad_id广告 ID
segment（广告变现数据）te_ads_object.placement广告位置
cost_valuete_ads_object.cost投放成本
af_cost_currencyte_ads_object.currency买量投放的币种
event_revenuete_ads_object.revenue变现收益
event_revenue_currency（广告变现数据）te_ads_object.currency变现收益的币种
country_codete_ads_object.country国家地区编码
platformte_ads_object.platform平台，即 Android、iOS 等
app_idte_ads_object.app_id应用 ID
app_namete_ads_object.app_name应用名
这篇文档对你有帮助吗？
本页内容