AppsFlyer Push API

TIP

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

概要

接口简介

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

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

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

集成流程

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

一、客户端 SDK 配置

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

1.1 方案一（自动集成）

• 如果您接入的 Android、iOS SDK
  • SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
  • SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件。详情请参考 安卓 SDK 对接文档 与 iOS SDK 对接文档
• 如果您接入的 Unity SDK 版本为 2.4.0 及以上 ，Unreal SDK 版本为 1.5.0 及以上可以直接使用本方案

WARNING

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

1. 初始化 TE 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() 再设置一遍访客 
IDString distinctId = ThinkingAnalyticsAPI.GetDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);
// 4、初始化 Appsflyer SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
TDAnalytics.login("account_id")
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER)

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、调用 enableThirdPartySharing 接口 设置 ta_distinct_id 到 appsflyer 事件中
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAppsFlyer];
// 3、强烈建议您使用 setCustomerUserId() 再设置一遍访客 
NSString *distinctId = [TDAnalytics getDistinctId];
[[AppsFlyerLib shared] customerUserID:distinctId];
// 4、初始化 Appsflyer SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
[TDAnalytics login:@"account_id"];
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAppsFlyer];

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、调用 enableThirdPartySharing 设置 ta_distinct_id 到 AF 事件中
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.APPSFLYER);
// 3、强烈建议您使用 setCustomerUserId() 再设置一遍访客 
var distinctId = TDAnalytics.GetDistinctId();
AppsFlyer.setCustomerUserId(distinctId);
// 4、初始化 AF SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
TDAnalytics.Login("account_id");
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.APPSFLYER);

// 1、初始化 Unreal SDK
UTDAnalytics::Initialize();
// 2、调用 enableThirdPartySharing 设置 ta_distinct_id 到 Appsflyer 事件中
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeAPPSFLYER"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
// 4、初始化 Appsflyer SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
UTDAnalytics::Login("account_id", AppID);
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeAPPSFLYER"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID)

TIP

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

如果您也需要调用 AF SDK 的 setAdditionalData() 方法，由于该方法调用多次会覆盖之前的参数，因此您可以按照以下代码，将参数传递给 TE SDK，TE 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() 方法，传入 TE 项目的访客 ID 与账号 ID。

1.2 方案二（手动集成）

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

WARNING

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

1. 初始化TE SDK。

2. 调用setAdditionalData 设置访客 ID。

3. 初始化 AF SDK。

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

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、获取 TE 的访客 ID, 对应 TE 中的 #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);

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
NSString *distinctId = [TDAnalytics getDistinctId];
// 3、将访客ID设置到 AF 采集事件中
NSDictionary *distinctData = @{@"ta_distinct_id": distinctId};
[[AppsFlyerLib shared] setAdditionalData:distinctData];
// 4、强烈建议您使用 setCustomerUserId() 再设置一遍访客 
[[AppsFlyerLib shared] customerUserID:distinctId];
// 5、初始化 AF SDK
//  。。。
// 6、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
NSString *accountId = @"ta_account_id";
[TDAnalytics login:accountId];
NSDictionary *customDataDict = @{
    @"ta_distinct_id": distinctId,
    @"ta_account_id": accountId
};
[[AppsFlyerLib shared] setAdditionalData:customDataDict];

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
var distinctId = TDAnalytics.GetDistinctId();

// 3、将访客ID设置到 AF 采集事件中
var distinctData = new Dictionary<string, string>
{
    { "ta_distinct_id" , distinctId}
};
AppsFlyer.setAdditionalData(distinctData);
// 4、强烈建议您使用 setCustomerUserId() 再设置一遍访客 
AppsFlyer.setCustomerUserId(distinctId);
// 5、初始化 AF SDK
//  。。。
// 6、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
var accountId = "account_id";
TDAnalytics.Login(accountId);
var additionalData = new Dictionary<string, string>
{
    { "ta_distinct_id" , distinctId},
    {"ta_account_id" , accountId}
};
AppsFlyer.setAdditionalData(additionalData);

经过以上设置后，回传数据中的custom_data 将带有 ta_distinct_id、ta_account_id 这两个字段，customer_user_id 则等于访客 ID。

二、方案配置

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

2.1 用户识别字段

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

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

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

2.2 事件表入库设置

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

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

2.3 用户属性入库规则

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

AppsFlyer 字段	标准化字段	说明
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	广告名

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

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

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

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

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

2.4 终端地址

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

若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE 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_source	te_ads_object.media_source	媒体渠道
monetization_network（广告变现数据）	te_ads_object.media_source	变现渠道
campaign	te_ads_object.campaign_name	广告计划名
af_c_id	te_ads_object.campaign_id	广告计划 ID
af_adset	te_ads_object.ad_group_name	广告组名
ad_unit（广告变现数据）	te_ads_object.ad_group_name	变现广告的 Unit 名
af_adset_id	te_ads_object.ad_group_id	广告组 ID
af_ad	te_ads_object.ad_name	广告名
af_ad_id	te_ads_object.ad_id	广告 ID
placement（广告变现数据）	te_ads_object.placement	广告位置
af_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	应用名

三、AppsFlyer Push API 配置

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

• 回传API 版本（Push API Version)
  • 请选择 2.0 版本
• HTTP 请求方法（HTTP method)
  • TE 系统同时支持 POST 和 GET 方式回传，我们建议选择 POST 方式
• 终端地址（EndpointURL）
  • 在 TE 系统后台 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)

DANGER

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

四、后续使用

4.1 数据入库检查

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

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

4.2 报表建议

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

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