Unity Ads Advertising Statistics API V2.0
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Advertising Statistics API V2.0 | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ | ✅ |
Unity Ads 广告投放数据2.0 通过 Advertising Statistics API v2.0 回传到 Thinking Analytics (后文简称 AE 系统) 的方案，该方案支持：
- 将 Unity Ads 的成本、点击、展示等基础报表指标的回传到 AE 系统
集成流程
- 登录 Unity 后台，获取将要接入数据的项目的「Organization ID」以及「API Key」
- 登录 AE 后台，进入三方集成模块，新增 Unity 集成方案，完成相关配置
- 查看 AE 系统是否成功接收数据，并完成报表搭建
一、获取授权信息
1.1 获取 Organization ID
进入到 Unity Ads User Acquisition 后台，选择左侧栏「Administration」页面下的「Settings」页面，在「Organization Settings」表格中找到并复制保存「Organization ID」。
1.2 获取 API Key 与 Secret
接下来，您需要创建服务账号（service account），并为其设置「广告统计 API 查看者（Advertise Stats API Viewer）」，使用该账号的 API Key 与 Secret 方可获取数据。以下展示的是从创建服务账号开始的完整流程：
- 创建服务账号
进入到 Unity Cloud 后台，在 Administration > Service accounts 页面中，点击右上角的创建按钮进入创建服务账号环节。
接着，根据需求输入服务账号名以及描述，并完成账号的创建。
- 创建授权 Key
在完成账号创建后，接着进入账号的设置页面，在「Keys」板块下创建一个新的授权 Key。
完成创建后，请记录下 Key ID、Secret Key 以及 Authorization header 并妥善保存，这些信息将在创建集成方案时被使用。
- 设置账号权限
接下来，您需要为该账号设置「广告统计 API 查看者（Advertise Stats API Viewer）」权限，在「Organization roles」板块下，点击创建角色流程进入到权限选择界面。
在权限选择界面，在「Growth」选项中，选择「Advertise Stats API Viewer」，完成权限设置。
二、方案配置
当您从 Unity 后台获得了授权信息后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 Unity Ads Advertising Statistics API V2.0 的配置界面，请您按照本章节内容完成方案的创建：
2.1 授权信息配置
点击「授权信息」下的「配置授权信息」按钮，在弹出框内填写您在上一步中获得的信息：
请完整填写您在 Unity 后台获取的信息，Authorization header 在填入时请包含前面的Basic 前缀
2.2 定时拉取
您可以在「定时拉取」模块设置 AE 系统定时拉取 Unity Ads Advertising Statistics API V2.0 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计入数据量，建议不要定时拉取太长时间的数据
2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义，字符串类型。 |
| source | time_granularity | 数据拉取的时间粒度，可以选择：
|
| metrics | 对应接口的指标字段，列表类型，可以自定义 | |
| group_by | 数据中的分组维度，列表类型，可以自定义 | |
| transfer | double_columns | 数据中的指标，列表类型，其中的字段会在数据接收时以数值类型入库，其余字段以字符串（或时间）入库。不建议调整 |
- 分组维度
以下是 Unity Advertising Statistics API V2.0 支持的分组维度，如需调整，可以将需要的分组维度的维度名写入 source.group_by 中
| 维度名 | 描述 | 入库字段名 | 是否默认拉取 |
|---|---|---|---|
| app | 按 App 分组 | app_id | 是 |
| app_name | 是 | ||
| campaign | 按 Campaign 分组 | campaign_id | 是 |
| campaign_name | 是 | ||
| country | 按国家（地区）分组 | country | |
| creativePack | 按 Creative Pack 分组 | creative_pack_id | 是 |
| creative_pack_name | 是 | ||
| creativePackType | 按 Creative Pack 的类型分组 | creative_pack_type | 是 |
| osVersion | 按系统版本分组 | os_version | 是 |
| platform | 按平台分组 | platform | 是 |
| sourceAppId | 按来源游戏分组 | source_app_id | |
| store | 按应用商店分组 | store | 是 |
targetGame | 按目标游戏分组 | target_id | 是 |
| target_store_id | 是 | ||
| target_name | 是 | ||
| eventType | 按 Unity 事件类型分组 | event_type | |
| eventName | 按 Unity 事件名分组 | event_name |
- 指标字段
除了分组维度外，Unity Ads Advertising Statistics API v2.0 也提供了以下指标字段。如需调整，可以将需要的指标名写入 source.metrics 中。
| 指标名 | 入库字段名 | 字段说明 | 是否默认拉取 |
|---|---|---|---|
| timestamp | timestamp | 事件时间 | 是 |
| starts | starts | 广告曝光次数 | 是 |
| views | views | 广告完播次数 | 是 |
| clicks | clicks | 广告点击次数 | 是 |
| installs | installs | 查看广告并安装次数 | 是 |
| spend | spend | 花费 | 是 |
| cpi | cpi | 每次安装成本 | |
| ctr | ctr | 点击通过率 | |
| cvr | cvr | 转化率 | |
| ecpm | ecpm | eCPM | |
| d[x]AdRevenue | d[x]_ad_revenue | N 日广告收益 | |
| d[x]AdRevenueRoas | d[x]_ad_revenue_roas | N 日广告收益回报率 | |
| d[x]IapRevenue | d[x]_iap_revenue | N 日内购收益 | |
| d[x]IapRoas | d[x]_iap_roas | N 日内购收益回报率 | |
| d[x]Purchases | d[x]_purchases | N 日内购次数 | |
| d[x]UniquePurchasers | d[x]_unique_purchasers | N 日首次内购用户数 | |
| d[x]Retained | d[x]_retained | N 日留存人数 | |
| d[x]RetentionRate | d[x]_retention_rate | N 日留存率 | |
| d[x]TotalRoas | d[x]_total_roas | N 日总收益回报率 | |
| d[x]LevelComplete | d[x]_level_complete | N 日通过特定关卡的用户数 | |
| d[x]CostPerLevelComplete | d[x]_cost_per_level_complete | N 日通过特定关卡的用户的平均花费 | |
| d[x]LevelCompleteRate | d[x]_level_complete_rate | N 日通过特定关卡的通过率 |
上表中[x] 可以替换为 0, 1, 3, 7, 14 这些实际数字，如 d7 表示直到第 7 日的指标
2.5 事件入库规则
- 使用数据中的 timestamp 字段，即数据聚合的时间字段，设置为聚合数据的 #event_time
- 如果没有重命名，数据的事件名为 -- unity_ads_api_data
- 其余字段均将入库
2.6 标准化字段
Unity Ads Advertising Statistics API v2.0 数据中的部分字段，AE 系统会进行标准化处理：
| 字段 | 标准化字段 | 含义 |
|---|---|---|
| campaign_name | te_ads_object.campaign_name | 广告计划名 |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| creative_pack_name | te_ads_object.ad_group_name | 广告组名 |
| creative_pack_id | te_ads_object.ad_group_id | 广告组 ID |
| country | te_ads_object.country | 国家地区编码 |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| starts | te_ads_object.impressions | 曝光量 |
| clicks | te_ads_object.clicks | 点击量 |
| installs | te_ads_object.installs | 转化量（安装） |
| spend | te_ads_object.cost | 买量成本 |