Adjust 数据集成解决方案
最近更新日期：2023-03-24
一、集成方案介绍
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
本文将介绍如何将 Adjust 数据回传到 Agentic Engine（后文简称 AE 系统） ，本方案支持：
- 通过实时回传功能回传用户粒度原始数据，涵盖转化、变现等数据
- 通过 Report Service API 回传聚合数据，涵盖曝光、点击、成本、变现等数据
- 如果您准备使用实时回传功能上报原始数据，请阅读 AE 系统用户识别规则，了解 AE 如何通过
#distinct_id和#account_id识别一个用户。 - 如果您准备使用 Report Service 获取聚合结果，请确保您已经阅读 AE 系统数据规则，理解 AE 的数据结构。另外，建议您将拉取数据所需的信息交给我们的客户成功经理，格式可参考数据集成配置信息模板。
流程
- 如果您使用实时回传方案，请遵循以下流程接入数据：
- 接入 Adjust 客户端 SDK 与 AE 客户端 SDK，在 Adjust SDK 中设置 AE 用户识别 ID，在 AE SDK 中设置 Adjust ID 以及 Android ID / IDFA / Web UUID（建议在 Adjust SDK 中上报自定义的注册/创建角色事件）
- 在 Adjust 的后台设置统一回传（Global callback）或单个事件回传（Single event callback）
- 由 AE 工作人员完成数据拉取开发工作，包括用户数据的回溯关联
- 在 AE 后台搭建看板、报表，并完成数据验收
- 如果您使用 Report Service 回传聚合数据，则可以遵循以下流程：
- 在 Adjust 后台，获取 Adjust User Token（API Token）和 Adjust App Token，将这些信息提供给 AE 工作人员
- 确定需要拉取的数据维度、指标类型、时间范围与时间粒度
- 由 AE 工作人员完成数据拉取开发工作
- 在 AE 后台搭建看板、报表，并完成数据验收
二、实时回传方案
| 接口名 | API 类型 | 产品化 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|---|
| 实时回传 | 推式 | 是 | 用户级别 | 是 | 是 | 是 |
Adjust 提供了一系列事件的实时回传能力，在 Adjust 后台选定需要回传的数据类型，并将 AE 系统的回调链接设置在回调地址处，即可实现用户级别明细数据的回传。
2.1 配置客户端 SDK
2.1.1 设置用户 ID
方案一（自动关联）：
如果您接入的 AE SDK 版本为 2.8.0~2.8.1 ，可以直接使用本方案
如果您接入的 AE SDK 版本为 2.8.2 及以上 ，您还需要安装三方数据插件
详情可参考 安卓 SDK 三方数据 与 iOS SDK 三方数据
// 初始化 AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// 开启 Adjust id关联
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_ADJUST);
// 初始化 Adjust SDK
// ...
// 注册或创角后，调用 login 设置账号 ID后，需要再次同步数据(可选)
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_ADJUST);
该方案的原理就是内部自动调用 Adjust SDK 的 addSessionCallbackParameter() 方法，传入 AE 项目的访客 ID 与账号 ID。
方案二：
本方案为手动调用 Adjust SDK 的 addSessionCallbackParameter() 方法设置 AE 项目的访客 ID 与账号 ID。
// 获取 AE 的访客 ID, 对应 AE 中的 #distinct_id
String distinctId = ThinkingAnalyticsAPI.GetDistinctId();
// 您的账号 ID (或 角色 ID)，对应 AE 中的 #account_id
String accountId = "{your_account_id}";
Adjust.addSessionCallbackParameter("ta_distinct_id", distinctId);
Adjust.addSessionCallbackParameter("ta_account_id", accountId);
// 初始化 Adjust SDK
// ...
为了确保 AE 用户 ID 可以正常获取，请勿在 Adjust SDK 中使用 addCallbackParameter 再次上报 AE 账号 ID 与 访客 ID
2.1.2 设置注册或创角事件（可选）
为了确保用户绑定关系符合预期，请根据您在 AE SDK 中设置的账号 ID 的类型，设置一个自定义事件：
- 账号 ID 为用户的账号 ID：在用户创建账号时使用 Adjust SDK 上报
- 账号 ID 为角色 ID（游戏行业）：可以在用户创建角色时使用 Adjust SDK 上报
2.1.3 Web 端配置方法
由于 Web 端与移动端的差异较大，您需要在 Adjust Web SDK 中通过以下代码获取 web_uuid，并将其通过 AE SDK 进行上报，设置成用户属性：
const webUUID = Adjust.getWebUUID();
接着，在后续配置回调链接时，使用 {web_uuid} 占位符进行回传，以确保可以和 AE 项目用户数据相关联。
2.2 配置回调链接
完成了客户端 SDK 的配置后，接下来需要在 Adjust 后台设置实时回传接口，这样就可以收到 Adjust 的用户粒度明细数据。
2.2.1 回传方法选择
Adjust 支持配置统一回传，也可以配置单个事件回传。由于广告收入（Ad revenue）事件不支持统一回传，因此我们建议您为回传事件进行单独配置。
以下是 Adjust 支持回传的事件以及我们建议接入的事件：
| 事件中文名 | 事件名 | 建议接入 |
|---|---|---|
| 展示 | impressions | |
| 点击 | clicks | |
| 安装 | install | 是 |
| 广告收入（广告收入套餐） | ad revenue (with Ad Revenue package) | 是 |
| 广告支出 | ad spend | |
| 会话 | sessions | |
| 应用事件 | app events | 按需接入 |
| 再归因 | reattributions | |
| 卸载 | uninstalls | |
| 重装 | reinstalls | |
| 再归因重装 | reattribution reinstalls | |
| 归因更新 | updated attributions | |
| 已删除用户 (GDPR) | erased users (GDPR) | |
| SAN 点击 | SAN clicks | |
| SAN 展示 | SAN impressions | |
| SKAdNetwork 安装 | SKAdNetwork installs | |
| SKAdNetwork 事件 | SKAdNetwork events | |
| 订阅 | subscriptions | |
| ATT 状态更新 (iOS) | ATT status updates (iOS) | |
| 被拒安装 | rejected installs | |
| 被拒再归因 | rejected reattributions |
2.2.2 回调链接的配置
建议您将所有需要回传的事件记录下来，在数据集成配置信息模板中进行写明，并将模板发送给 AE 工作人员。AE 工作人员会将各事件对应的回调链接发送给您。请依次将回调地址设置到下图红框位置。
2.2.3 回调占位符的配置
回调占位符是回调链接中用来指定回传参数的一种表达式，一般会用 {} 括起，比如 {campaign_name} 占位符意味着回调数据中将会带有 campaign_name 的值。不同回调数据可以支持不同的占位符，您可以访问 Adjust 占位符说明文档来获取更多信息，如果您需要添加，请从上述文档中寻找待增加的属性，并在数据集成配置信息模板中进行写明。
2.3 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中，一条回调数据写入一条事件数据：
- 使用数据中的
ta_distinct_id和ta_account_id作为 AE 项目的用户识别 ID - 使用数据中的 created_at_milli 字段，作为事件的 #event_time，若 created_at_milli 不存在，则取 created_at 的值作为 #event_time
- 数据事件名为 Adjust 的事件名加前缀 adjust_（如 impression 事件入库后为 adjust_impression）
- 回调链接中配置的其他字段将全数入库
在默认情况下，如果未能获取到数据中的 ta_distinct_id 和 ta_account_id ，则该条数据将被视作无效数据，直接丢弃。如果您希望保留这些数据，可以联系 AE 工作人员进行配置，这些数据将会记录在事件表中，访客 ID 为固定值 -- "without_id"，且这些数据不会进行用户属性入库
2.3.1 曝光、点击、成本数据的事后关联
由于 impression、click、Ad spend 的回传数据中不包含 AE 项目的用户识别 ID。如果您希望接入此类数据，AE 系统会自动将这些数据挂在一个“虚拟用户”身上。
接着，如果这些事件中存在可以标识用户的字段（如 adjust_id 与 Android ID/IDFA 或 web_uuid），且用户属性中也存在对应的字段，AE 工作人员可以通过数据回溯的方式，定时将这些事件关联到 AE 用户
| 数据类型 | 说明 | 入库 AE 后事件名 | 事件的虚拟用户 |
|---|---|---|---|
| impression | 曝光 | adjust_impression | adjust_impression_vu |
| click | 点击 | adjust_click | adjust_click_vu |
| cost_update | 成本 | adjust_cost_update | adjust_cost_update_vu |
三、Report Service API
由于 Adjust 用户级别的数据（实时回传接口）里面没有自归因平台（Google, Facebook等）成本数据，因此我们可以通过 Report Service 获取全平台的聚合成本数据。
具体文档可参考：https://help.adjust.com/zh/article/reports-endpoint
接口基本信息
| 接口名 | API 类型 | 产品化 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|---|
| Report Service API | 拉式 | 否 | 聚合数据 | 是 | 是 | 是 | 是 | 是 |
3.1 接入前准备工作
请获取以下参数并发送给 AE 工作人员：
- Adjust User Token（即用户的 API Token）
- 您可以在 Adjust 后台获取您的 API Token，在后台点击左上角菜单，选择「账户信息」（管理员用户请选择「我的账户」，在「您的数据」标签页中找到「用户详情」，点击底部齿轮按钮），再点击「API 识别码」，即可获取您的 API Token
- Adjust App Token
- 您可以在 Adjust 后台获取您需要接入的应用的 App Token
3.2 数据拉取
3.2.1 分析维度
以下是 Report Service 支持的分析维度，包括时间粒度（只可选一个），以及分组维度（可多选）
- 时间粒度
| 维度 | 数据类型 | 描述 | 示例 | 是否默认 |
|---|---|---|---|---|
hour | 日期 | ISO 格式日期值：YYYY-MM-DDTHH:MM:SS | 2021-05-11T17:00:45 | |
| day | 日期 | 日期值格式：YYYY-MM-DD | 2021-05-11 | 是 |
- 分组维度
| 维度 | 数据类型 | 描述 | 示例 | 是否默认 |
|---|---|---|---|---|
os_name | 字符串 | 操作系统 | 取值：android、Bada、blackberry、iOS、Linux、Mac OS、server、symbian、unknown、WebOS、Windows、windows-phone | 是 |
device_type | 字符串 | 设备类型 | 取值：bot、console、iPod、Mac、PC、phone、server、simulator、tablet、TV、unknown | 是 |
| app | 字符串 | 应用名称 | - | 是 |
| app_token | 字符串 | Adjust 中的应用 ID | - | 是 |
| store_id | 字符串 | 商店应用 ID | com.random.app | 是 |
| store_type | 字符串 | 应用安装来源商店 | google_play | 是 |
app_network | 字符串 | 应用标识 | 格式：<store_type>:<store_id> 如：google_play:com.random.app | 是 |
| currency | 字符串 | 币种 | Euro | 是 |
| currency_code | 字符串 | 3 字符的 ISO 4217 货币代码 | EUR | 是 |
network | 字符串 | 广告渠道的名称 | 取值：Organic, AppLovin, Facebook Installs, Instagram Installs | |
| campaign | 字符串 | 包含推广活动名称和 ID | - | 是 |
| campaign_network | 字符串 | 渠道的推广活动名称 | - | 是 |
| campaign_id_network | 字符串 | 渠道的推广活动 ID | - | 是 |
| adgroup | 字符串 | 包含广告组名称和 ID | - | 是 |
| adgroup_network | 字符串 | 渠道的广告组名称 | - | 是 |
| adgroup_id_network | 字符串 | 渠道的广告组 ID | - | 是 |
| source_network | 字符串 | 基于渠道的可选值， 一般与 adgroup_network 相同 | - | 是 |
| source_id_network | 字符串 | source_app 值 | - | 是 |
| creative | 字符串 | 包含素材名称和 ID | - | 是 |
| creative_network | 字符串 | 渠道素材名称 | - | 是 |
| creative_id_network | 字符串 | 渠道素材 ID | - | 是 |
| country | 字符串 | 国家/地区名称 | United States of America | 是 |
| country_code | 字符串 | 2 字符 ISO 3166 国家/地区代码 | US | 是 |
| region | 字符串 | 业务地区 | APAC | 是 |
| partner_name | 字符串 | Adjust 系统中的合作伙伴名称 | AppLovin | 是 |
| partner_id | 字符串 | Adjust 系统中的合作伙伴 ID | 34 | 是 |
3.2.2 涵盖指标
Report Service 支持的指标相当丰富，本节仅展示部分常用指标，您可以访问 Adjust 官网文档获取详细的指标列表，如果需要自定义拉取的指标，请在数据集成配置信息模板中注明
- 转化指标
| 字段 | 定义 | 公式 | 字段名 | 是否默认 |
|---|---|---|---|---|
| 平均 DAUs | 所选时间段的平均日活跃用户 | (D0 DAU + D1 DAU + DAY N DAU) / 所选时间段天数 | daus | 是 |
| 平均 MAUs | 所选时间段的平均 MAU | (M0 MAU + M1 MAU + MONTH N MAU) / 所选时间段月数 | maus | 是 |
| 平均 WAUs | 所选时间段的平均 WAU | (W0 WAU + W1 WAU + WEEK N WAU) / 所选时间段周数 | waus | 是 |
基本 Sessions 数 | 用户的 sessions 数，排除安装和再归因 | - | base_sessions | 是 |
| 点击数 | 追踪到的点击数 | - | clicks | 是 |
| 点击数 (渠道) | 由渠道 API 上报的点击数 | - | network_clicks | 是 |
| 点击转化率 (CCR) | 安装数与点击数的比值 | 安装数 / 点击数 | click_conversion_rate | 是 |
| 点击率(CTR) | 点击和曝光的占比 | 点击数 / 曝光数 | ctr | 是 |
| 离归因 | 发生离归因的次数 | - | deattributions | 是 |
| 行使 GDPR 遗忘权的用户数 | 行使了欧盟 GDPR 遗忘权的用户数。Adjust 将永久删除这些用户的个人数据 | - | gdpr_forgets | 是 |
| 曝光数 | 追踪到的广告曝光数 | - | impressions | 是 |
| 曝光数 (渠道) | 由渠道 API 上报广告曝光数 | - | network_impressions | 是 |
| 安装曝光比 | 安装数与曝光数的占比 | 安装数 / 曝光数 | impression_conversion_rate | 是 |
| 安装数 | 追踪到的安装您的 App 的用户数 | - | installs | 是 |
| 安装数 (渠道) | 由渠道 API 上报的安装数 | - | network_installs | 是 |
| 安装差异数 | 安装数与渠道 API 上报的安装数的差值 | 安装数 - 安装数 (渠道) | network_installs_diff | 是 |
| 每千次展示安装数 (IPM) | 每一千次广告展示引发的安装数 | 1000 * 展示转化比 | installs_per_mile | 是 |
| 限制追踪设备的安装数 | 打开限制追踪的设备 (LAT) 的安装数 | - | limit_ad_tracking_installs | 是 |
| 限制追踪设备的安装占比 | 限制追踪设备的安装与安装数的比值 | 限制追踪设备的安装数 / 安装数 | limit_ad_tracking_install_rate | 是 |
| 限制追踪设备的再归因数 | 打开限制追踪的设备 (LAT) 的再归因数 | - | limit_ad_tracking_reattributions | 是 |
| 限制追踪设备的再归因占比 | 限制追踪设备的再归因数 与再归因数的比值 | 限制追踪设备的再归因数 / 再归因数 | limit_ad_tracking_reattribution_rate | 是 |
| 非自然量安装数 | 不被归因为自然量的用户的安装数 | - | non_organic_installs | 是 |
| 自然量安装数 | 归因为自然量的用户的安装数 | - | organic_installs | 是 |
| 再归因数 | 再归因的用户数 | - | reattributions | 是 |
| 再归因的重装数 | 再归因的用户的重新安装数 | - | reattribution_reinstalls | |
| 重新安装数 | 重新安装的次数 需购买 Uninstall and Reinstall Growth Solution | - | reinstalls (否则请求报错) | |
| 总 Sessions 数 | 总 Sessions 数包括安装和再归因 | base_sessions + installs + reattributions | sessions | 是 |
- 成本指标
| 字段 | 定义 | 公式 | 字段名 | 是否默认 |
|---|---|---|---|---|
| 广告支出 | 广告的总支出（由拉取参数决定） | 点击支出 + 曝光支出 + 安装支出 | cost | 是 |
| 广告支出(归因) | Adjust 追踪到的广告支出 | 点击支出 + 曝光支出 + 安装支出 | adjust_cost | 是 |
广告支出(渠道) | 由渠道 API 上报的广告支出 | 点击支出 + 曝光支出 + 安装支出 | network_cost | 是 |
| 广告支出差异 | 广告支出(归因)与广告支出(渠道)的差值 | 广告支出(归因)- 广告支出(渠道) | network_cost_diff | 是 |
| 点击成本 | 广告点击消耗的成本支出 | - | click_cost | 是 |
| 付费点击数 | 有广告支出的广告点击数 | - | paid_clicks | 是 |
| eCPI (所有安装) | 所有安装的平均有效支出 | 广告支出 / 安装 | ecpi_all | 是 |
| eCPI (渠道) | 由渠道 API 上报的安装的平均有效支出 | 渠道 API 上报的广告支出 / 渠道 API 上报的安装数 | network_ecpi | 是 |
| eCPI (付费安装) | 付费安装的平均有效支出 | 渠道 API 上报的广告支出 / 付费安装数 | ecpi | 是 |
| eCPM (归因) | 由归因数据上报 eCPM 数据 | (广告支出 / 付费曝光数) * 1000 | ecpm | 是 |
| eCPM (渠道) | 由渠道 API 上报 eCPM 数据 | (渠道支出 / 渠道付费曝光) * 1000 | network_ecpm | 是 |
| eCPC | 每次点击的平均有效支出 | 广告支出 / 付费点击数 | ecpc | 是 |
| 曝光成本 | 曝光消耗的成本支出 | - | impression_cost | 是 |
| 付费曝光数 | 有广告支出的付费曝光数 | - | paid_impressions | 是 |
| 安装成本 | 安装消耗的成本支出 | - | install_cost | 是 |
| 付费安装数 | 有广告支出的付费安装数 | - | paid_installs | 是 |
- 收益指标
| 字段 | 定义 | 公式 | 字段名 | 是否默认 |
|---|---|---|---|---|
| 广告曝光数 | 广告的总曝光数 | - | ad_impressions | 是 |
| 广告收入 | 广告总收入 | - | ad_revenue | 是 |
| 人群累计广告收入 | 所选时间段内安装的用户到当前的广告收入 例：选择时间为 1/1 号～1/31 号，今天为 5/1 号，则计算 1/1 号～1/31 号安装的用户到 5/1 号的广告收入 | - | cohort_ad_revenue | 是 |
| 千次展示广告收入 | 每一千次广告展示的平均收入 | (广告收益 / 广告曝光) * 1000 | ad_rpm | 是 |
| 内购收入 | 内购收入 | - | revenue | 是 |
| 人群累计内购收入 | 所选时间段内安装的用户到当前的内购收入 例：选择时间为 1/1 号～1/31 号，今天为 5/1 号，则计算 1/1 号～1/31 号安装的用户到 5/1 号的内购收入 | - | cohort_revenue | 是 |
| 总收入 | 包含广告收入以及内购收入的总收入 | 广告收入 + 内购收入 | all_revenue | 是 |
| 人群累计总收入 | 所选时间段内安装的用户到当前的总收入 例：选择时间为 1/1 号～1/31 号，今天为 5/1 号，则计算 1/1 号～1/31 号安装的用户到 5/1 号的总收入 | 人群累计内购收入 + 人群累计广告收入 | cohort_all_revenue | 是 |
| ARPU (全部) | 包含所有收入的平均活跃用户收益 | 总收入 / 总DAU | arpdau | 是 |
| ARPU(仅广告) | 仅包含广告收入的平均活跃用户收益 | 广告收入 / 总DAU | arpdau_ad | 是 |
| ARPU (仅内购) | 仅包含内购收入的平均活跃用户收益 | 内购收入 / 总DAU | arpdau_iap | 是 |
| 毛利润 | 总收入减去总成本 | 总收入 - 总成本 | gross_profit | 是 |
| 人群毛利润 | 所选时段安装的用户的毛利润 | 人群的总收入 - 成本 | cohort_gross_profit | 是 |
| 人群ROI | 所选时段安装的用户的毛利润除以成本 | 人群的毛利润 / 成本 | return_on_investment | 是 |
| 内购数 | 追踪到的内购事件数 | - | revenue_events | 是 |
| 收入成本比 (RCR) | 所选时段安装的用户的收入与成本的比值 | 人群的总收入 / 总成本 | revenue_to_cost | 是 |
| ROAS (总收入) | 计算总收入的 ROAS | (广告收入 + 内购收益) / 成本 | roas | 是 |
| ROAS (广告收入) | 只计算广告收入的 ROAS | 广告收入 / 成本 | roas_ad | 是 |
| ROAS (内购收入) | 只计算内购收入的 ROAS | 内购收益 / 成本 | roas_iap | 是 |
3.2.3 接口参数
-
时间：
- 可以拉取以天为单位的数据
- 时区可以自定义
3.2.4 入库规则
- 由于 Report Service 是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 day 或 hour 字段，即数据的日期，设置为聚合数据的 #event_time
- Report Service 的数据事件名为 -- adjust_report_service_ad_spend
- 其余指标、维度字段均会入库
3.3 数据集成配置信息模板
在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理，我们将根据该信息模板完成 Adjust Report Service 的数据拉取：
数据接口：Adjust Report Service
---------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
Adjust User Token (API Token): XXX
Adjust App Token: XXX
---------
API 配置
历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取最近 X 日的数据（由于 Adjust 存在事后的数据校正，因此建议定时拉取最近几天的数据，确保能够拉取修正后的数据）
时间粒度：(天/小时)
分组维度：xxx,xxx
聚合指标：xxx,xxx
四、联调测试与集成后数据使用
- 联调测试
可以在「数据管理」 ->「用户属性管理」页面查看相关归因数据：
| Adjust 回传字段 | 说明 | 入库 AE 后用户属性名称 | 数据类型 |
|---|---|---|---|
| network_name | 渠道 | #adjust_network_name | 文本 |
| campaign_name | 广告计划 | #adjust_campaign_name | 文本 |
| adgroup_name | 广告组 | #adjust_adgroup_name | 文本 |
| creative_name | 广告素材 | #adjust_creative_name | 文本 |
若您开启了事件表入库，在「数据管理」 ->「事件管理」页面查看相关事件数据，事件名和在 Adjust 定义的事件名相同；impression, click, cost_update, ad_revenue 事件映射表如下：
| activity_kind 的值 | 说明 | 入库 AE 后事件名 |
|---|---|---|
| impression | 曝光 | adjust_impression |
| click | 点击 | adjust_click |
| cost_update | 成本 | adjust_cost_update |
| ad_revenue | 收益 | adjust_ad_revenue |
五、常用 FAQ
请查看 Adjust FAQ 部分