Adjust 实时回传

TIP

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

概要

接口简介

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

Adjust 提供了一系列事件的实时回传 (opens new window)能力，在 Adjust 后台选定需要回传的数据类型，并将 TE 系统的回调链接设置在回调地址处，即可实现用户级别明细数据的回传。

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

集成流程

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

一、客户端 SDK 配置

集成 Adjust 数据的第一步，是在客户端完成 TE SDK 与 Adjust SDK 的打通，在 Adjust 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 初始化和开启自动集成代码必须在 Adjust 的 SDK 初始化之前完成，请按照以下步骤操作：

1. 初始化TE SDK。

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

3. 初始化 Adjust SDK。

以下为各端 SDK 的代码样例：

// 1、初始化 Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2、调用 enableThirdPartySharing 接口设置 ta_distinct_id 到 adjust 事件中
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.ADJUST);
// 3、初始化 Adjust SDK
//  。。。
// 4、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.ADJUST);

// 1、初始化 iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
[TDAnalytics startAnalyticsWithConfig:config];
// 2、调用 enableThirdPartySharing 接口 设置 ta_distinct_id 到 adjust 事件中
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAdjust];
// 3、初始化 Adjust SDK
//  。。。
// 4、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
[TDAnalytics login:@"account_id"];
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeAdjust];

// 1、初始化 Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2、调用 enableThirdPartySharing 设置 ta_distinct_id 到 adjust 事件中
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.ADJUST);
// 3、初始化 Adjust SDK
//  。。。
// 4、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
TDAnalytics.Login("account_id");
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.ADJUST);

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

TIP

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

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

1.2 方案二（手动集成）

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

WARNING

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

1. 初始化TE SDK。

2. 调用addSessionCallbackParameter 设置访客 ID。

3. 初始化 Adjust 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设置到 adjust 采集事件中
Adjust.addSessionCallbackParameter("ta_distinct_id", distinctId);
// 4、初始化 Adjust SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
String accountId = "ta_account_id";
TDAnalytics.login(accountId);
Adjust.addSessionCallbackParameter("ta_account_id", accountId);

// 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设置到 adjust 采集事件中
[Adjust addSessionCallbackParameter:@"ta_distinct_id" value:distinctId];
// 4、初始化 Adjust SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
NSString *accountId = @"ta_account_id";
[TDAnalytics login:accountId];
[Adjust addSessionCallbackParameter:@"ta_account_id" value:accountId];

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

// 3、将访客ID设置到 adjust 采集事件中
Adjust.addSessionCallbackParameter("ta_distinct_id", distinctId);

// 4、初始化 Adjust SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
var accountId = "account_id";
TDAnalytics.Login(accountId);
Adjust.addSessionCallbackParameter("ta_account_id", accountId);

// 1、初始化 Unreal SDK
UTDAnalytics::Initialize();
// 2、获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
FString distinctId = UTDAnalytics::GetDistinctId();

// 3、将访客ID设置到 adjust 采集事件中
Adjust::AddSessionCallbackParameter(TEXT("ta_distinct_id"), distinctId);
// 4、初始化 Adjust SDK
//  。。。
// 5、注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
FString accountId = "account_id";
UTDAnalytics::Login(accountId);
Adjust::AddSessionCallbackParameter(TEXT("ta_account_id"), accountId);

二、方案配置

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

2.1 用户识别字段

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

如果您按照本文档上一步进行客户端 SDK 配置，可以直接使用默认值：

• 账号 ID 关联字段：ta_account_id
• 访客 ID 关联字段：ta_distinct_id
  

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

默认规则为：

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

2.2 事件表入库设置

打开「事件表入库设置」开关后，Adjust 回传的数据都将写入到事件表中，我们建议您开启事件数据入库。

2.3 用户属性入库规则

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

Adjust 字段	入库 TA 后用户属性名称	说明
network_name	te_ads_object.media_source	渠道
campaign_name	te_ads_object.campaign_name	广告计划
adgroup_name	te_ads_object.ad_group_name	广告组
creative_name	te_ads_object.ad_name	广告素材

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

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

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

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

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

2.4 终端地址

2.4.1 默认配置

若您配置了系统和项目级别数据上报地址，则显示如下链接；您可以直接复制该地址，并粘贴至 Adjust 后台实时回传配置处：

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

2.4.2 自定义宏

Adjust 的回调地址中包含一种称为宏的结构，表示方法为{宏名称}。宏可以被认为是一种占位符，当 Adjust 需要回传的数据中包含与宏对应的字段。以 {campaign_name} 为例， Adjust 会在回传数据时，将 campaign_name 的值填入回调地址中宏所在位置。您可以的参考 Adjust 的回调演示视频 (opens new window)，了解宏的作用。

以下展示的是 TE 界面上的建议您复制以下地址，请注意，地址中您需要替换以下内容：

• {receiver-host} ：数据上报地址，即 TE 后台「项目管理」-「接入配置」-「数据上报地址」处的公网地址
• {app-id}：TE 的项目 APP ID

TIP

旧版本的数据源地址与当前不一致，请注意分辨，我们建议您使用新地址。

另外，如果您有其他参数希望添加，可以查看该文档 (opens new window)

2.5 集成配置

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

模块	名称	含义
extra_params	track_without_id	由于 Adjust 的部分回传数据中，可能不包含 TE 的用户 ID，此时您可以将这个参数改为 true，系统会将"without_id"作为缺省的用户 ID，从而使该条数据可以入库，默认为 false，即系统将丢弃缺失 TE 的用户 ID 的数据

2.6 事件入库规则

• 使用数据中的 created_at_milli 字段，作为事件的 #event_time，若 created_at_milli 不存在，则取 created_at 的值作为 #event_time
• 数据事件名为：
  • 安装：install
  • 广告收入：ad_revenue
  • 其他事件：在 Adjust 后台的事件名
• 回调链接中配置的其他字段将全数入库

2.7 标准化字段

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

原始字段	标准化字段	含义
network_name	te_ads_object.media_source	媒体渠道
ad_mediation_platform	te_ads_object.media_source	变现渠道
campaign_name	te_ads_object.campaign_name	广告计划名
google_ads_campaign_name	te_ads_object.campaign_name	广告计划名（仅 Google Ads 数据）
google_ads_campaign_id	te_ads_object.campaign_id	广告计划 ID（仅 Google Ads 数据）
adgroup_name	te_ads_object.ad_group_name	广告组名
google_ads_adgroup_name	te_ads_object.ad_group_name	广告组名（仅 Google Ads 数据）
google_ads_adgroup_id	te_ads_object.ad_group_id	广告组 ID（仅 Google Ads 数据）
creative_name	te_ads_object.ad_name	广告名
google_ads_creative_id	te_ads_object.ad_id	广告 ID（仅 Google Ads 数据）
ad_revenue_placement	te_ads_object.placement	变现广告位置
google_ads_placement	te_ads_object.placement	广告位置（仅 Google Ads 数据）
cost_amount	te_ads_object.cost	投放成本
cost_currency	te_ads_object.currency	买量投放的币种
revenue_usd	te_ads_object.revenue	变现收益
【USD】定值	te_ads_object.currency	变现收益的币种
country	te_ads_object.country	国家地区编码
os_name	te_ads_object.platform	平台，即 Android、iOS 等
app_id	te_ads_object.app_id	应用 ID
app_name	te_ads_object.app_name	应用名

三、Adjust 实时回传接口配置

完成TE后台配置后，接下来请使用管理员账号登录至Adjust后台。在左侧菜单中，点击「AppView」 - 「所有应用」（All apps），找到需要配置回传的目标应用，并点击「服务器回传」（Server callbacks）按钮，进入到回传配置页。

随后，在回传配置页中，点击右上角的新建回调按钮，使用「经典设置」 （Classic Setup）创建新回调。

我们评估了所有回传事件后，建议您单独为安装和广告收入事件配置单个事件回传，以下是我们建议回传的事件：

事件中文名	事件名（Trigger）
安装	install
广告收入（需要购买 Adjust Growth Solution）	ad revenue


我们建议您使用以下宏作用于安装事件（install）的回传

https://{receiver-host}/attribution/callback/adjust/{app-id}?network_name={network_name}&campaign_name={campaign_name}&adgroup_name={adgroup_name}&creative_name={creative_name}&activity_kind={activity_kind}&created_at_milli={created_at_milli}&timezone={timezone}&event_name={event_name}&cost_amount={cost_amount}&cost_currency={cost_currency}&publisher_parameters={publisher_parameters}&app_id={app_id}&app_name={app_name}&country={country}&os_name={os_name}&app_version={app_version}

广告收入事件（ad revenue），建议使用以下宏

https://{receiver-host}/attribution/callback/adjust/{app-id}?network_name={network_name}&campaign_name={campaign_name}&adgroup_name={adgroup_name}&creative_name={creative_name}&activity_kind={activity_kind}&created_at_milli={created_at_milli}&timezone={timezone}&event_name={event_name}&cost_amount={cost_amount}&cost_currency={cost_currency}&publisher_parameters={publisher_parameters}&app_id={app_id}&app_name={app_name}&country={country}&os_name={os_name}&currency={currency}&revenue={revenue_float}&placement={ad_revenue_placement}&ad_revenue_unit={ad_revenue_unit}&ad_revenue_network={ad_revenue_network}&app_version={app_version}

四、后续使用

4.1 数据入库检查

您可以在「数据管理」页面查看回传事件是否入库：

• 安装：install
• 广告收入：ad_revenue
• 其他事件：在 Adjust 后台的事件名

4.2 报表建议

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

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

五、附录

5.1 Facebook 的用户归因占位符显示为 Unattributed 的解决方案

背景

Facebook 在弃用 amm 之后，来自 Facebook 的用户归因占位符（如 {campaign_name} ）等都回传 Unattributed。如果要是还想获取安卓平台的 Facebook 来源用户的归因信息，需要使用新的占位符。

解决步骤-Adjust 侧配置

1. 安装 Install Referrer 插件

首先，请确保您的安卓应用中有集成下列 SDK 组件： https://help.adjust.com/zh/article/get-started-android-sdk?src=search_page#set-up-install-referrer

1. 在 Adjust Facebook 模块上添加来自 Facebook 的 Decryption Key

接下来，您可以在 Facebook developer account (https://developers.facebook.com/) (控制面板 > 设置 > 基本 > Android (Google Play) Install Referrer Decryption Key) 中获取 Decryption Key。每个Decryption Key 都对应唯一 Facebook App ID。该值为获取应用数据来源的关键，请将其添加至 Adjust 控制面板中 (对应安卓应用的应用设置 > 合作伙伴设置 > Facebook)

1. 使用新的占位符

以下为此解决方案中用于获取应用数据的新占位符。我们现支持在安装活动回传中添加这些占位符，未来希望能将其延伸到其他活动上。目前，我们建议您先以 {adid} 或其他内部 ID 来映射安装及安装后事件数据。

• {fb_install_referrer}: 解码后的 Facebook install referrer 完整值
• {fb_install_referrer_ad_id}: Facebook install referrer 完整值下的 "ad_id"
• {fb_install_referrer_adgroup_id}: Facebook install referrer 完整值下的"adgroup_id"
• {fb_install_referrer_adgroup_name}: Facebook install referrer 完整值下的 "adgroup_name"
• {fb_install_referrer_campaign_id}: Facebook install referrer 完整值下的 "campaign_id"
• {fb_install_referrer_campaign_name}: Facebook install referrer 完整值下的 "campaign_name"
• {fb_install_referrer_campaign_group_id}: Facebook install referrer 完整值下的 "campaign_group_id"
• {fb_install_referrer_campaign_group_name}: Facebook install referrer 完整值下的 "campaign_group_name"
• {fb_install_referrer_account_id}: Facebook install referrer完整值下的 "account_id"
• {fb_install_referrer_ad_objective_name}: Facebook install referrer完整值下的 "ad_objective_name"

解决步骤-TE 后台配置

进入到 Adjust 实时回传方案，主要会受到影响的是「用户属性入库规则」，如果您希望将 Facebook 的归因字段设置为用户属性，请将宏名称填写到「来源属性名」列，并设置目标属性名：