目录
此内容是否有帮助?

# AppsFlyer 集成方案

本文将介绍如何在 TE 后台接入 AppsFlyer 数据，目前 TE 后台支持接入的是 AppsFlyer 的 Push API (opens new window)，如需了解如何接入 AppsFlyer 的其他接口数据，请参考 AppsFlyer 数据集成解决方案 (opens new window)

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 集成，并完成相关配置
  3. 登录 AppsFlyer 后台，完成回传配置
  4. 查看 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 后调用以下代码开启：

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

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

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

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

// 在调用 TE SDK 的 login 设置账号 ID 后，需要再次向 AF SDK 同步数据
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

注意

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

如果您也需要调用 AF 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
);

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

# 1.2 方案二（手动集成）

手动集成方案，需要您在 AF SDK 中使用 setAdditionalData() 配置 TE 项目的访客 ID 与账号 ID， 以下是安卓端的代码样例：

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

// 获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String distinctId = ThinkingAnalyticsAPI.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);
...

// 在调用 TE 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。

# 二、TE 三方集成页面配置

完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 AppsFlyer 的配置。下图是 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
 广告名

注意

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

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

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

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

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

# 2.4 数据源

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

若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到 AppsFlyer 配置页的「数据源」复制终端地址。

# 三、AppsFlyer Push API 配置

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

  • 回传 API 版本（Push API Version)
    • 请选择 2.0 版本
  • HTTP 请求方法（HTTP method)
    • TE 系统同时支持 POST 和 GET 方式回传，我们建议选择 POST 方式
  • 终端地址（Endpoint URL）
    • 在 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 等
      • 需要作为事件属性或者用户属性的字段
      • 事件相关字段：event_time_selected_timezone
  • 回传的应用内事件（In-app events）
    • 按需选择回传的事件，如需回传，请在事件信息类型 (Event Messages) 中勾选回传应用内事件 (Install in-app events)

注意

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

# 四、数据入库逻辑

# 4.1 用户识别规则

TE 系统将根据「用户识别与关联」中的配置，对回传数据进行用户识别，将 AF 回传的用户粒度数据能够关联在 TE 项目中的对应用户身上。

以上图为例，以下是用户识别规则：

  • 账号 ID：检查 custom_data 字段是否包含 ta_account_id，如果存在，将其作为数据的 #account_id，如果没有，则留空
  • 访客 ID：检查 customer_user_id 是否存在，如果有，将其设置为 #distinct_id。如果没有，检查 custom_data 字段是否包含 ta_distinct_id，如果有，将其设置为 #distinct_id，如果没有，则留空
  • 如果账号 ID 和访客 ID 皆为空，则该条数据将被视作无效数据，直接丢弃

# 4.2 事件入库规则

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

# 4.3 标准化字段

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

原始字段 标准化字段 含义
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
 应用名

# 4.4 用户属性入库规则

  • 根据用户识别规则，将事件数据关联到对应的 TE 用户身上
  • 根据用户属性入库规则，确定用户属性设置逻辑是 user_set、user_setOnce 或 user_add
  • 从指定事件或全事件中获取需要写入用户属性的字段，并将其以给定属性名与类型写入用户表

# 五、后续使用

# 5.1 数据入库检查

最后，请您检查 TE 系统是否接收到了 AF 的回传数据，您可以按照以下方法进行检查：

  • 在详细数据中查看

若平台接入状态为「已接入」，则说明已经从该平台接收到了数据，且数据已经入库。此时，您可以直接在集成页的「详情」TAB 页查看收到的最近 1000 条数据。点击具体的一行可查看该数据的明细信息，包括转化前与转化后的数据，可以复制或导出该条数据，或者点击右上角下载完整数据：

  • 在其他产品模块查看

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

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

# 5.2 报表建议

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

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

# 六、FAQ

请参考 AppsFlyer FAQ (opens new window)

← Adjust 集成方案 →