AppsFlyer 数据集成解决方案

最近更新 2026/10/05

最近更新日期：2023-04-04

一、集成方案介绍

提示

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

概要

本文介绍如何将 AppsFlyer 的数据回传到 Agentic Engine（后文简称 AE 系统），本方案支持 AppsFlyer 的多种数据集成方法，以下表格展示了各种数据集成方法的特性以及数据类型，您可以点击标题跳转至方案的对应章节：

接口	数据粒度	API 类型	产品化	数据更新频率	请求次数限制
Push API 用户数据	用户级别	推式	是	实时	无限制
Pull API 用户级别数据接口	用户级别	拉式	否	实时	每次请求最多 1M 行每个 APP 每天最多 24 次请求每天每个账户最多 120 次请求
Pull API 聚合数据	聚合数据	拉式	否	实时	每分钟最多请求 1 次拉取时间范围 0-2 天内：无限制拉取时间范围 3 天或以上：每个 APP 每天最多 24 次请求每天每个账户最多 120 次请求
Master API	聚合数据	拉式	否	按天	每次请求不限行每天请求次数不限
Cohort API	聚合数据	拉式	否	按天	无限制
Data Locker	用户级别 / 聚合数据	拉式	-	按天/小时	根据转存云存储的限制

警告

注意，部分平台会限制用户级别数据的部分字段回传，包括归因信息、收益数据与成本数据等

提示

部分接口为 AppsFlyer 的收费功能，在使用前请咨询您在 AppsFlyer 的客户经理了解接口的使用权限。

二、Push API 用户级别数据接口（已产品化）

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Push API	推式	是	用户级别	是		是	是	是	是

Push API 可以实时获取 AppsFlyer 的用户级别数据，其中包括了展示、点击、激活、收益数据等。成本数据由于 AF 平台的数据限制，可能无法获取。

提示

注意 Push API 集成已经在 AE 系统后台产品化，建议参考相关产品文档进行界面化集成配置。

在接入 Push API 用户级别数据前，请确保您已经阅读 AE 系统用户识别规则，并理解 AE 系统如何通过 #distinct_id 和 #account_id 识别一个用户。AppsFlyer Push API 接口的数据集成流程如下图：

查看原图

2.1 客户端 SDK 设置

如果要将 Push API 的用户级别数据与 AE 项目的用户数据进行打通，就需要在 AppsFlyer SDK 中上报 AE 项目的账号 ID 与访客 ID，以下是客户端 SDK 的设置方法。

方案一（自动集成）：

提示

如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案

如果您接入的 AE SDK 版本为 2.8.2 及以上，您还需要安装三方数据插件

本方案是自动集成方案，请在初始化 AE 客户端 SDK 后调用以下代码开启，详情请参考安卓 SDK 三方数据与 iOS SDK 三方数据

// 初始化 AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// 开启 AE SDK 的 AppsFlyer ID 关联功能
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

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

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

// 在调用 AE SDK 的 login 设置账号 ID 后，需要再次向 AF SDK 同步数据
instance.login("account_id");
instance.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");
instance.enableThirdPartySharing(
    TDThirdPartyShareType.TD_APPS_FLYER,
    additionalData
);

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

方案二（手动集成）：

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

// 初始化 AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// 获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String distinctId = instance.getDistinctId();

// 将访客 ID 通过 setAdditionalData() 设置到 AF SDK
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

// 强烈建议您使用 setCustomerUserId() 再设置一遍访客 ID
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

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

// 在调用 AE SDK 的 login 设置账号 ID 后，需要再次向 AF SDK 同步数据
String accountId = "your_account_id";
instance.login(accountId);
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。

注意：如果您使用产品化配置方法接入 AppsFlyer Push API 的数据，则需要在关联字段处填写：

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

2.2 配置回传地址

接下来使用管理员账号登录 AppsFlyer 后台，在「Integration」- 「API Access」找到 Push API 部分，按照以下方法设置回调地址：

AppsFlyer Push API 端点配置页，1–6 标出请求方式、地址、事件类型、消息字段、应用内事件和保存

回传 API 版本（Push API Version)
- 请选择 2.0 版本
HTTP 请求方法（HTTP method)
- AE 系统同时支持 POST 和 GET 方式回传，我们建议选择 POST 方式
终端地址（Endpoint URL）
- AE 工作人员将向您提供数据终端接收地址
事件信息类型 (Event Messages)
- 您至少需要选中激活 (Install) 和激活应用内事件 (Install in-app events) 。如果您还有其他需要回传的事件数据，可以按需勾选
回传字段 (Message Fields)
- 消息字段至少要包括以下信息：
  - 移动归因相关字段：media_source、channel、af_adset、af_ad 等
  - 用户识别 ID 相关字段：custom_data、customer_user_id、event_value 等
  - 需要作为事件属性或者用户属性的字段
  - 事件相关字段：event_time_selected_timezone
回传的应用内事件（In-app events）
- 按需选择回传的事件，例如客户端上报的 ta_registration 事件

警告

注意，如果需要 Facebook 的数据，您需要在 AF 后台 Facebook 渠道设置中同意 Facebook 数据使用协议 (Terms of Service)，否则无法获取 Facebook 的用户级别数据。

2.3 数据入库

2.3.1 用户识别规则

根据之前客户端 SDK 设置的用户识别字段的逻辑，您需要确定相应的用户识别规则，使 Push API 回传的用户粒度数据能够关联在 AE 项目中的对应用户身上。

在默认情况下，我们会在回传数据中根据以下规则寻找用户标识字段：

Step 1: 检查 custom_data 字段是否包含 ta_account_id / ta_distinct_id，即 setAdditionalData() 设置的字段
Step 2: 检查 event_value 字段是否包含 ta_account_id / ta_distinct_id，即 AppsFlyer 自定义事件设置的字段
Step 3: 如果事件为 Install 事件（event_name: install），则会检查 customer_user_id 字段，如有，则将 customer_user_id 作为 #distinct_id，即 setCustomerUserId() 设置的字段

在每一步骤中，如果能获取到任一有效的 ID，则停止后续步骤的检查。如果经过全部 3 个步骤的确认，仍然无法获得有效用户 ID。在默认情况下，该条数据将被视作无效数据，直接丢弃。如果您希望保留这些数据，可以联系 AE 工作人员进行配置，这些数据将会记录在事件表中，访客 ID 为固定值 -- "without_id"，且这些数据不会进行接下来的用户属性入库

如果您设置的用户识别字段与上述不同，请在数据集成配置信息模板中记录下来。

2.3.2 数据入库规则

默认情况下，回传的数据不会写成事件数据，如果您需要将其写为事件数据，则所有接收到的事件都将写为事件数据，以下是事件数据的入库规则：

根据用户识别规则，将事件数据归在对应的 AE 用户身上
使用数据中的 event_time_selected_timezone 字段，取其中的时间和时区信息，时间作为 #event_time，时区写为 #zone_offset。如果该字段为空，则取 event_time 作为 #event_time，时区 #zone_offset 会被设置为 0
数据事件名为该事件在 AppsFlyer 中的事件名
其余字段都将会入库

2.3.3 用户属性入库配置

在默认情况下，我们会从数据中读取以下四个字段的值，并将其设置为用户属性：

AppsFlyer 字段	AE 标准化字段	说明
media_source	te_ads_object.media_source	渠道
campaign	te_ads_object.campaign_name	广告系列
af_adset	te_ads_object.ad_group_name	广告组
af_ad	te_ads_object.ad_name	广告

除此之外，您还可以自定义需要入库的用户属性，包括用户属性的入库规则（即使用 user_set 还是 user_setOnce），如果您需要进行用户属性的自定义，请在数据集成配置信息模板中记录下来。

2.4 数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

接口：AppsFlyer Push API
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
用户识别规则：XXX 作为 访客 ID/账号 ID（不填则为默认）
是否入库事件：否/是
是否保留未获取用户识别 ID 的数据：否/是（只有入库事件时才会有效）
入库用户属性：XXX，XXX（不填则为默认）

三、Pull API 用户级别数据

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Pull API Raw Data	拉式	否	用户级别	是	是	是			是

Pull API Raw Data 是拉取式的用户级别数据接口，非常适合拉取用户粒度的历史数据。

3.1 接入前准备工作

3.1.1 获取 API Token

请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Pull API Raw Data 的 V2.0 API Token。

AppsFlyer 侧边栏 Integration 菜单，选中 API Access

3.1.2 获取 App ID

可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678

3.1.3 客户端 SDK 设置

如果要将 Pull API 用户级别数据与 AE 项目的用户数据进行打通，就需要在 AppsFlyer SDK 中上报 AE 项目的账号 ID 与访客 ID，以下是客户端 SDK 的设置方法。

方案一（自动集成）：

提示

如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案

如果您接入的 AE SDK 版本为 2.8.2 及以上，您还需要安装三方数据插件

本方案是自动集成方案，请在初始化 AE 客户端 SDK 后调用以下代码开启，详情请参考安卓 SDK 三方数据与 iOS SDK 三方数据

// 初始化 AE 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 = instance.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

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

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

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() 方法，传入 AE 项目的访客 ID 与账号 ID。

方案二（手动集成）：

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

// 初始化 AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// 获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String distinctId = instance.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。

3.2 涵盖字段

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

字段	中文名	默认获取	类型
Attributed Touch Type	归因类型（曝光、点击）	是
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-5]	子参数 [1-5]
Cost Model	成本模型 (CPC/CPI/CPM/Other)	是
Cost Value	成本值	是	数值
Cost Currency	成本货币类型	是
Contributor [1-3] Partner	贡献者 [1-3] 合作伙伴
Contributor [1-3] Media Source	贡献者 [1-3] 媒体渠道
Contributor [1-3] Campaign	贡献者 [1-3] 广告计划
Contributor [1-3] Touch Type	贡献者 [1-3] 归因类型
Contributor [1-3] Touch Time	贡献者 [1-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.3 接口参数

时间：
- 拉取以日为时间单位的数据（仅支持拉取近 90 天的数据）
- 默认的数据时区为 UTC 时间

3.4 数据入库规则

Pull API 用户级别数据接口会入库多种数据，每种数据的处理规则如下：

Installs 数据
- 拉取仅包含 user acquisition（UA）的 Installs 数据以及 Organic Installs 数据
- 数据默认以用户属性形式写入
- 支持以事件形式写入，事件名为 af_install
- 以用户识别字段配置来确定用户识别字段，如果没有配置用户识别规则，默认取数据中的 customer_user_id 作为访客 ID。没有获取到用户识别字段，则该条数据将会被抛弃。
- 所有字段均会入库
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。没有获取到用户识别字段，则该条数据将会被抛弃。
- 所有字段均会入库

3.5 数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

接口：AppsFlyer Pull API Raw Data
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
用户识别规则：XXX 作为 访客 ID/账号 ID（不填则为默认）
接入的数据：Install、Ad Revenue
写入用户属性的 Install 事件的属性：xxx，xxx（不填则为默认） 

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd（仅支持拉取近 90 天的数据）
定时拉取：每天 X 点拉取前一天的数据

四、Pull API 聚合指标接口

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Pull API 聚合指标	拉式	否	聚合数据		是	是	是	是	是

AppsFlyer Pull API 聚合指标接口提供了不同类型的聚合指标数据，目前 AE 系统支持的数据类型有 Partners (by date) 与 Geo (by date)。

4.1 接入前准备工作

4.1.1 获取 API Token

请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Pull API 的 V2.0 API Token。

4.1.2 获取 App ID

可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678

4.2 涵盖字段

4.2.1 Partner (by date) 数据

本节介绍的是 Partner (by date) 类型的数据，该报告基于 LTV 数据，即拉取指定时间段内安装的新用户的后续数据。

AppsFlyer Export Data 页的报告列表，红框标出 Partners (by date) 报告

由于 Facebook 的数据格式与其他媒体渠道的格式不同，因此 AE 系统会分别拉取仅有 Facebook 数据与所有平台数据，以下是 Partner (by date) 能够获取到的字段：

字段名	入库名	仅 Facebook 数据	全平台数据
Date	#event_time	✓	✓
Agency/PMD (af_prt)	agency_pmd_af_prt	✓	✓
Media Source (pid)	media_source_pid	✓	✓
Campaign	campaign_name（Facebook） campaign_c（全平台）	✓	✓
Campaign ID	campaign_id	✓
Adgroup ID	adgroup_id	✓
Adgroup Name	adgroup_name	✓
Adset ID	adset_id	✓
Adset Name	adset_name	✓
ARPU	arpu	✓	✓
Average eCPI	average_ecpi	✓	✓
Clicks	clicks	✓	✓
Conversion Rate	conversion_rate	✓	✓
CTR	ctr	✓	✓
{your event name}(Unique users)	{your_event_name}_unique_users	✓	✓
{your event name} (Event counter)	{your_event_name}_event_counter	✓	✓
{your event name} (Sales in XXX)	{your_event_name}_sales_in_usd	✓	✓
Impressions	impressions	✓	✓
Installs	installs	✓	✓
Loyal Users	loyal_users	✓	✓
Loyal Users/Installs	loyal_users_installs	✓	✓
ROI	roi	✓	✓
Sessions	sessions	✓	✓
Total Cost	total_cost	✓	✓
Total revenue	total_revenue	✓	✓

4.2.2 Geo (by date) 数据

本节介绍的是 Geo (by date) 类型的数据，该报告基于 LTV 数据，即拉取指定时间段内安装的新用户的后续数据。

由于 Facebook 的数据格式与其他媒体渠道的格式不同，因此 AE 系统会分别拉取仅有 Facebook 数据与所有平台数据，以下是 Geo (by date) 能够获取到的字段：

字段名	入库名	仅 Facebook 数据	全平台数据
Country	country	✓	✓
Date	#event_time	✓	✓
Agency/PMD (af_prt)	agency_pmd_af_prt	✓	✓
Media Source (pid)	media_source_pid	✓	✓
Campaign	campaign_name（Facebook） campaign_c（全平台）	✓	✓
Campaign ID	campaign_id	✓
Adgroup	adgroup_id	✓
Adgroup Name	adgroup_name	✓
Adset ID	adset_id	✓
Adset Name	adset_name	✓
ARPU	arpu	✓	✓
Clicks	clicks	✓	✓
Conversion Rate	conversion_rate	✓	✓
{your event name}(Unique users)	{your_event_name}_unique_users	✓	✓
{your event name} (Event counter)	{your_event_name}_event_counter	✓	✓
{your event name} (Sales in XXX)	{your_event_name}_sales_in_usd	✓	✓
Installs	installs	✓	✓
Loyal Users	loyal_users	✓	✓
Sessions	sessions	✓	✓
Total revenue	total_revenue	✓	✓

4.3 接口参数

时间：
- 拉取以日为时间单位的数据
- 默认的数据时区为 UTC 时间

4.4 数据入库规则

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

由于 Pull API 聚合指标接口返回的是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
使用数据中的 Date 字段，即用户的安装日期，作为事件的 #event_time
数据事件名为：
- Partner (by date)
  - appsflyer_facebook_partner_by_date（Facebook 数据）
  - appsflyer_partner_by_date（全平台数据）
- Geo (by date)
  - appsflyer_facebook_geo_by_date（Facebook 数据）
  - appsflyer_geo_by_date（全平台数据）
其他字段将全数入库

4.5 数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

接口：AppsFlyer Pull API 聚合数据接口
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
数据拉取时区：XXX（默认使用 UTC 时间）
数据拉取类型：Partner (by date)/Geo (by date)

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前一天的数据

五、Master API

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Master API	拉式	否	聚合数据		是	是	是	是

Master API 支持自定义分析维度以及聚合指标，相较于 Pull API 聚合指标接口而言，灵活性更强。

5.1 接入前准备工作

5.1.1 获取 API Token

请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Master API 的 V2.0 API Token。

5.1.2 获取 App ID

可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678

5.2 涵盖字段

Master API 包含了多种类型的指标，其中比较常用的指标大类有：LTV KPIs、Retention KPIs 以及 Cohort KPIs。由于 Cohort KPIs 支持的分析维度要窄于其他指标大类，因此 AE 系统会分开拉取包含以及不包含 Cohort KPIs 的数据，以下是这两类数据涵盖的字段：

分析维度

字段名	af_groupings	入库名	排除 Cohort KPIs 数据	包含 Cohort KPIs 数据
App ID	app_id	app_id	✓	✓
Media Source	pid	media_source	✓	✓
Agency	af_prt	partner	✓
Campaign	c	campaign	✓	✓
Adset	af_adset	adset	✓
Ad	af_ad	ad	✓
Channel	af_channel	channel	✓
Publisher ID	af_siteid	publisher_id_af_siteid	✓	✓
Keywords	af_keywords	keywords
Is Primary Attribution	is_primary	is_primary_attribution
Campaign ID	af_c_id	campaign_id
Adset ID	af_adset_id	adset_id
Ad ID	af_ad_id	ad_id
Install Time	install_time	install_time	✓	✓
Touch Type	attributed_touch_type	touch_type	✓
GEO	geo	geo	✓	✓

指标字段

以下列举的是 Master API 的部分常用字段，如需了解全量字段，可以访问 AppsFlyer 官网文档：

提示

新增的指标字段将添加在 排除 Cohort KPIs 数据 中，如需增加，可以在数据集成配置信息模板中写明

入库名	描述	排除 Cohort KPIs 数据	包含 Cohort KPIs 数据
impressions	曝光数	✓	✓
clicks	点击数	✓	✓
installs	安装数	✓	✓
cr	转化率	✓	✓
sessions	Session 数	✓	✓
loyal_users	忠实用户安装数	✓	✓
loyal_users_rate	忠实用户比例	✓	✓
cost	总成本	✓	✓
revenue	总收益	✓	✓
roi	ROI	✓	✓
arpu_ltv	平均生命周期价值	✓	✓
average_ecpi	平均eCPI	✓	✓
uninstalls	卸载数	✓	✓
uninstalls_rate	卸载率	✓	✓
retention_day_[x]	第 N 天留存用户数（N = 0,1,2,3,4,5,6,7,15,30）	✓
retention_rate_day_[x]	第 N 天留存用户率（N = 0,1,2,3,4,5,6,7,15,30）	✓
cohort_day_[x]_total_revenue_per_user	第 N 日累积收益（N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90）		✓
cohort_day_[x]_revenue_per_user	第 N 日当天收益（N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90）		✓
cohort_[x]_days_total_revenue_per_user	同第 N 日累积收益（N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90）		✓

5.3 接口参数

时间：
- 拉取以日为时间单位的数据
- 默认的数据时区为 UTC 时间

5.4 数据入库规则

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

由于 Master API 聚合指标接口返回的是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
使用数据中的 install_time 字段，即用户的安装时间，作为事件的 #event_time
数据事件名为：
- 包含 Cohort KPIs 数据
  - appsflyer_master_ltv_act_cohort_kpis
- 排除 Cohort KPIs 数据
  - appsflyer_master_ltv_act_retention_kpis
其他字段将全数入库

5.5 数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

拉取数据接口：AppsFlyer Master API 聚合数据接口
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
数据拉取时区：XXX（默认使用 UTC 时间）
新增指标：XXX, XXX（如果是与事件相关的 activity 指标，可以指定需要拉取指标数据的事件名；新增指标将添加在排除 Cohort KPIs 数据，即 appsflyer_master_ltv_act_retention_kpis 事件上）

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前一天的数据

六、Cohort API

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Cohort API	拉式	否	聚合数据		是	是			是

Cohort API 同样也是聚合数据 API。相比其他聚合数据 API，数据指标的形态更类似于 AppsFlyer 的 Cohort Dashboard以及 AE 系统的留存分析模型的数据结果，即第 N 日（或累计第 N 日）指标。

6.1 接入前准备工作

6.1.1 获取 API Token

请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Cohort API 的 V2.0 API Token。

6.1.2 获取 App ID

可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678

6.2 涵盖字段

分析维度

需要注意的是，Cohort API 最多支持 7 个分析维度，以下是默认的分析维度，如果需要调整，请在数据集成配置信息模板中注明：

字段名	入库名	默认
Ad	af_ad	✓
Ad ID	af_ad_id
Campaign	c	✓
Campaign ID	af_c_id
Channel	af_channel	✓
Media Source	pid	✓
Sub Param 1	af_sub1
Keywords	af_keywords
Agency	af_prt
Conversion Type (1)	cohort_type
Site ID	site_id
Attributed Touch Type (3)	attributed_touch_type
Adset	af_adset	✓
Adset ID	af_adset_id
Country	geo
Date	date	✓

警告

请注意，如果您需要拉取 Facebook(Meta) 的数据，则分析维度请不要同时选择 af_channel 与 geo，否则将无法获取 Facebook 的成本数据

指标字段

需要注意的是，Cohort API 会返回 3 类默认指标以及一个额外指标，以下是默认的指标字段，如果需要调整，请在数据集成配置信息模板中注明：

指标类型	入库名	描述	默认
users（必有）	users	人群总用户数（与时间窗口无关）	✓
ecpi（必有）	ecpi	人群总eCPI（与时间窗口无关）	✓
cost（必有）	cost	人群总成本（与时间窗口无关）	✓
"event_name"（自定义事件）	"event_name"_unique_users_day_N	第 N 日自定义事件触发用户数
	"event_name"_count_day_N	第 N 日自定义事件完成数
	"event_name"_rate_day_N	第 N 日自定义事件完成率
	"event_name"_sum_day_N	第 N 日由自定义事件产生的收益额
revenue	revenue_count_day_N	第 N 日收益事件触发数	✓
revenue	revenue_sum_day_N	第 N 日收益额	✓
ROAS	roas_rate_day_N	第 N 日 ROAS
roi	roi_rate_day_N	第 N 日 ROI
sessions	sessions_unique_users_day_N	第 N 日 Session 触发用户数（如果是累计指标则不返回该数据）
	sessions_count_day_N	第 N 日 Session 数
	sessions_rate_day_N	第 N 日留存率（ Session 触发用户数 / 人群总用户数）
uninstalls	uninstalls_count_day_N	第 N 日卸载数
uninstalls	uninstalls_rate_day_N	第 N 日卸载率

注：上表中入库名列中的 N 代表第 N 日指标，默认取值范围为 0-30

6.3 接口参数

时间：
- 拉取以日为时间单位的数据
- 默认的数据时区为 UTC 时间
- 可以选择数据是每日独立（即展示当天的指标），还是累计数据（即从第 0 日累计至第 N 日）
- 可以选择是否允许非完整天（比如计算的第 N 日为今天）的数据回传

6.4 数据入库规则

默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：

由于 Cohort API 聚合指标接口返回的是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
使用数据中的 date 字段，即用户的归因/转化时间，作为事件的 #event_time
数据事件名为：appsflyer_cohort_api
其他字段将全数入库

6.5 数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：

拉取数据接口：AppsFlyer Cohort API 聚合数据接口
--------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
数据拉取时区：XXX（默认使用 UTC 时间）
是否允许非完整天数据：是/否（默认“是”）
数据的时间聚合类型：当天/累计（默认为累计）

分组维度: XXX，XXX （默认 date,pid,geo,c,af_adset,af_ad,af_channel）
指标字段：XXX （默认为 revenue，仅可设置一个）

历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取：每天 X 点拉取前 N 天的数据

七、Data Locker 与 Cost ETL

Data Locker 是 AppsFlyer 的数据转存服务，可以支持将多种数据转存到 AWS 或者 GCS 云存储上。

Cost ETL 是 AppsFlyer 的成本数据转存服务，可以将各媒体渠道的广告系列成本数据转存到 AWS 或者 GCS 云存储上。

目前 AE 系统已经支持集成 AWS S3 以及 GCS 的数据，您可以根据转存的云存储类型，查看下列文档：

AWS S3
- S3 数据 DataX 接入方式：使用 DataX 插件完成数据接入
GCS
- Firebase-Bigquery-GCS 数据迁移技术方案：通过代码方式（GCS 库）将数据经过清洗传输到 AE 系统，可以参考该文档的 2.2.2 以及 2.2.3 部分

八、联调测试与集成后数据使用

1. 联调测试

1.1 Push API 接口

可以在「数据管理」 ->「用户属性管理」页面查看相关归因数据，若有相关用户属性，则代表集成成功。

AppsFlyer 回传字段	入库 AE 后用户属性名称	数据类型
media_source	#appsflyer_media_source	文本
campaign	#appsflyer_campaign	文本
af_adset	#appsflyer_adset	文本
af_ad	#appsflyer_ad	文本

若您开启了事件表入库，在「数据管理」 ->「事件管理」页面查看相关事件数据，事件名和在 AppsFlyer 定义的事件名相同。

1.2 Pull API 和 Master API 聚合数据接口

可以在「数据管理」 ->「事件管理」页面查看相关事件，若有相关事件，则代表集成成功。

接口	报告名称	入库 AE 后事件名称	数据类型
Pull API	所有媒体渠道投放报告-按日	appsflyer_partner_by_date	文本
Pull API	Facebook 投放报告-按日	appsflyer_facebook_partner_by_date	文本
Master API	LTV, Activity, Retention 相关 KPIs	appsflyer_master_ltv_act_retention_kpis	文本
Master API	LTV, Activity, Retention 外加 Cohort 相关 KPIs	appsflyer_master_ltv_act_retention_cohort_kpis	文本

2. 数据使用

2.1 围绕归因信息做分析

2.2 对比不同媒体按照渠道、广告组、广告计划、广告素材维度计算激活、成本、收益、ROAS

AppsFlyer 报告示例数据，按日期、代理、媒体渠道和广告系列列出展示、点击、安装、收入等指标

2.3 在一个平台同时查看营销数据和用户行为数据，减少跨平台使用

2.4 数据联动分析，比如和变现、其他媒体渠道数据打通

2.5 通过 revenue / cost 计算不同媒体渠道的 ROAS

2.6 通过非自然用户的关键用户行为（比如付费前的某个事件：某个核心玩法的留存）来分析这批用户的质量，从而减少从分析到决策的时间

2.7 事件属性集成后数据类型

通过 AppsFlyer Pull API 拉取的数据，事件属性默认「按字符串类型接入」，您可以通过 AE 系统的虚拟属性功能将字符串类型的字段转换为其他类型，例如：

将 install 属性转换为数值类型："af_install_number" （数据类型选择数值）
将 total_cost 属性转换为数值类型："af_total_cost_number" （数据类型选择数值）

九、常用 FAQ

参考 AppsFlyer FAQ

这篇文档对你有帮助吗？

一、集成方案介绍​

概要​

二、Push API 用户级别数据接口（已产品化）​

2.1 客户端 SDK 设置​

2.2 配置回传地址​

2.3 数据入库​

2.3.1 用户识别规则​

2.3.2 数据入库规则​

2.3.3 用户属性入库配置​

2.4 数据集成配置信息模板​

三、Pull API 用户级别数据​

3.1 接入前准备工作​

3.1.1 获取 API Token​

3.1.2 获取 App ID​

3.1.3 客户端 SDK 设置​

3.2 涵盖字段​

3.3 接口参数​

3.4 数据入库规则​

3.5 数据集成配置信息模板​

四、Pull API 聚合指标接口​

4.1 接入前准备工作​

4.1.1 获取 API Token​

4.1.2 获取 App ID​

4.2 涵盖字段​

4.2.1 Partner (by date) 数据​

4.2.2 Geo (by date) 数据​

4.3 接口参数​

4.4 数据入库规则​

4.5 数据集成配置信息模板​

五、Master API​

5.1 接入前准备工作​

5.1.1 获取 API Token​

5.1.2 获取 App ID​

5.2 涵盖字段​

5.3 接口参数​

5.4 数据入库规则​

5.5 数据集成配置信息模板​

六、Cohort API​

6.1 接入前准备工作​

6.1.1 获取 API Token​

6.1.2 获取 App ID​

6.2 涵盖字段​

6.3 接口参数​

6.4 数据入库规则​

6.5 数据集成配置信息模板​

七、Data Locker 与 Cost ETL​

八、联调测试与集成后数据使用​

1. 联调测试​

2. 数据使用​

九、常用 FAQ​

一、集成方案介绍

概要

二、Push API 用户级别数据接口（已产品化）

2.1 客户端 SDK 设置

2.2 配置回传地址

2.3 数据入库

2.3.1 用户识别规则

2.3.2 数据入库规则

2.3.3 用户属性入库配置

2.4 数据集成配置信息模板

三、Pull API 用户级别数据

3.1 接入前准备工作

3.1.1 获取 API Token

3.1.2 获取 App ID

3.1.3 客户端 SDK 设置

3.2 涵盖字段

3.3 接口参数

3.4 数据入库规则

3.5 数据集成配置信息模板

四、Pull API 聚合指标接口

4.1 接入前准备工作

4.1.1 获取 API Token

4.1.2 获取 App ID

4.2 涵盖字段

4.2.1 Partner (by date) 数据

4.2.2 Geo (by date) 数据

4.3 接口参数

4.4 数据入库规则

4.5 数据集成配置信息模板

五、Master API

5.1 接入前准备工作

5.1.1 获取 API Token

5.1.2 获取 App ID

5.2 涵盖字段

5.3 接口参数

5.4 数据入库规则

5.5 数据集成配置信息模板

六、Cohort API

6.1 接入前准备工作

6.1.1 获取 API Token

6.1.2 获取 App ID

6.2 涵盖字段

6.3 接口参数

6.4 数据入库规则

6.5 数据集成配置信息模板

七、Data Locker 与 Cost ETL

八、联调测试与集成后数据使用

1. 联调测试

2. 数据使用

九、常用 FAQ