跳到主要内容

AppsFlyer Push API

最近更新 2026/10/05
提示

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

概要​

接口简介​

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

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

在开始接入 AF 数据前，请确保您已经阅读 AE 系统用户识别规则，理解 AE 如何通过 #distinct_id 和 #account_id 识别一个用户

集成流程​

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

一、客户端 SDK 配置​

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

1.1 方案一（自动集成）​

  • 如果您接入的 Android、iOS SDK

  • 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案

提示

请注意 AE 的 SDK 初始化和开启自动集成代码必须在 AppsFlyer 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化 AE SDK。

2. 调用`enableThirdPartySharing` 自动设置访客 ID。

3. 初始化 AppsFlyer SDK。

以下各端 SDK 的代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、调用 enableThirdPartySharing 接口设置 ta_distinct_id 到 appsflyer 事件中
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
// 3、强烈建议您使用 setCustomerUserId() 再设置一遍访客 ID
String distinctId = TDAnalytics.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);
// 4、初始化 Appsflyer SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
提示

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

如果您也需要调用 AF SDK 的 setAdditionalData() 方法，由于该方法调用多次会覆盖之前的参数，因此您可以按照以下代码，将参数传递给 AE SDK，AE SDK 内部会将参数进行拼接合并。以下代码为 Android 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
);

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

1.2 方案二（手动集成）​

手动集成方案，需要您在 AF SDK 中使用 setAdditionalData() 接口设置 AE 项目的访客 ID 与账号 ID。

提示

请注意 AE 的 SDK 初始化和调用 setAdditionalData 接口必须在 AF SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化AE SDK。

2. 调用`setAdditionalData` 设置访客 ID。

3. 初始化 AF SDK。

以下各端 SDK 手动集成代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String distinctId = TDAnalytics.getDistinctId();

// 3、将访客ID设置到 AF 采集事件中 
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

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

// 5、初始化 AppsFlyer SDK
...

// 6、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
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。

二、方案配置​

完成 SDK 配置后，接下来需要您登录 AE 系统后台，在「三方集成」模块中完成 AppsFlyer 的配置。下图是 AppsFlyer 的配置界面：

2.1 用户识别字段​

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

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

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

2.2 事件表入库设置​

打开「事件表入库设置」开关后，回传的数据（包括激活事件和应用内事件）都将写入到事件表中

我们建议您开启事件数据入库。但需要注意，默认情况下，我们会接收所有 AF 回传的数据。如果回传的事件类型过多，会导致 AE 项目的事件量过度膨胀。因此建议在 AF 平台的设置回传时，只选择必要事件进行回传。

2.3 用户属性入库规则​

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

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

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

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

在此，您可以修改用户属性从哪些事件来。如果您不希望用户属性被频繁写入，可以关闭「包含所有事件」，并将来源事件名修改为 install。这样配置，则 AE 系统只会从 AF 回传的 install 事件中提取需要写入用户属性的字段并进行写入。入库方式默认是 user_setOnce，也就是只会保留首次上报的信息。

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

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

2.4 终端地址​

终端地址中展示了 AE 系统接收 AppsFlyer 回传数据的地址。请您直接复制该地址，在接下来进行 AF 回传配置时，请将该地址填入：

若此处没有显示地址，请进入右上角菜单「项目管理 → 项目配置 → 接入配置」配置公网地址，也可以点击配置页提示条里的「数据上报地址」链接进入。该地址即 AE SDK 中配置的数据上报地址。配置后再回到 AppsFlyer 配置页，在「终端地址」处复制地址。

2.5 事件入库规则​

  • 使用数据中的 event_time_selected_timezone 字段，取其中的时间和时区信息，时间作为 #event_time，时区写为 #zone_offset。如果 event_time_selected_timezone 为空，则取 event_time 作为 #event_time，时区 #zone_offset 会被设置为 0
  • 数据事件名为该事件在 AppsFlyer 中的事件名
  • 其余字段都将会入库

2.6 标准化字段​

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

原始字段标准化字段含义
media_sourcete_ads_object.media_source媒体渠道
monetization_network（广告变现数据）te_ads_object.media_source变现渠道
campaignte_ads_object.campaign_name广告计划名
af_c_idte_ads_object.campaign_id广告计划 ID
af_adsette_ads_object.ad_group_name广告组名
ad_unit（广告变现数据）te_ads_object.ad_group_name变现广告的 Unit 名
af_adset_idte_ads_object.ad_group_id广告组 ID
af_adte_ads_object.ad_name广告名
af_ad_idte_ads_object.ad_id广告 ID
placement（广告变现数据）te_ads_object.placement广告位置
af_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应用名

三、AppsFlyer Push API 配置​

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

  • 回传 API 版本（Push API Version）

    • 请选择 2.0 版本

  • HTTP 请求方法（HTTP method）

    • AE 系统同时支持 POST 和 GET 方式回传，我们建议选择 POST 方式

  • 终端地址（Endpoint URL）

    • 在 AE 系统后台 AppsFlyer 配置页的「终端地址」一栏中获取地址，直接粘贴即可

  • 事件信息类型 (Event Messages)

    • 您至少需要选中激活 (Install) 事件，如果您希望回传其他应用内事件 (Install in-app events) ，请在此处勾选，并在回传的应用内事件（In-app events）中填入待回传事件的事件名

  • 回传字段 (Message Fields)

    • 消息字段至少要包括以下信息：

      • 移动归因相关字段：media_source、channel、af_adset、af_ad 等
      • 用户识别 ID 相关字段：custom_data、customer_user_id、event_value 等
      • 需要作为事件属性或者用户属性的字段：如 app_version、platform 等
      • 事件相关字段：event_time_selected_timezone

  • 回传的应用内事件（In-app events）

    • 按需选择回传的事件，如需回传，请在事件信息类型 (Event Messages) 中勾选回传应用内事件 (Install in-app events)
提示

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

四、后续使用​

4.1 数据入库检查​

您可以在「数据管理」页面查看回传事件、用户属性是否被创建。

您也可以在分析模型，如事件分析模型、用户属性分析模型中通过分析的方式检查数据是否入库。

以下提供几个构建报表的建议：

  1. 在事件分析模型中，使用 AF 回传数据搭建广告投放、广告变现核心指标，创建广告分析报表
  2. 在留存分析模型中，结合回传数据的广告变现与游戏内付费事件，计算各媒体渠道、广告计划等粒度包含广告变现的 LTV
  3. 在漏斗分析模型中，将安装事件加入到新用户转化漏斗中，并使用媒体渠道、广告计划等粒度分析不同来源用户的转化情况
这篇文档对你有帮助吗？
本页内容