Airbridge Actuals Report
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 曝光 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Actuals Report | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
Airbridge Actuals Report 提供了聚合的报表数据，包含成本、曝光、点击、转化等指标。本集成方案用于在 AE 后台定时拉取 Airbridge 报表数据，接口采用异步任务模式：AE 会先创建报表任务，再轮询任务状态，并在任务完成后分页读取结果。
集成流程
- 在 Airbridge 后台获取授权信息
app_name与api_token - 登录 AE 后台，进入三方集成模块，新增 Airbridge Actuals Report 方案，并完成相关配置
- 查看 AE 系统是否成功接收数据，并完成报表搭建
一、获取 Airbridge 授权信息
使用 Airbridge Actuals Report 前，需要准备以下授权信息。
| 授权信息 | 是否必填 | 含义 |
|---|---|---|
| app_name | 是 | Airbridge 应用名称，用于拼接 API 请求路径 |
| api_token | 是 | Airbridge API 调用凭证 |
二、方案配置
获取完 Airbridge 授权信息之后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 Airbridge Actuals Report 的配置界面，请您按照本章节内容完成方案的创建：
2.1 授权信息配置
在授权信息配置中填写从 Airbridge 获取的 app_name、api_token。
2.2 定时拉取
您可以配置方案的定时拉取频率。启用后，AE 系统会按配置周期向 Airbridge 发起 Actuals Report 取数任务。
Airbridge Actuals Report 支持拉取的时间范围最多为过去1000天，单次最多拉取400天。
2.3 事件表入库设置
您可以控制数据是否以事件形式写入。打开「事件表入库设置」开关后，AE 系统会将 Airbridge Actuals Report 拉取到的聚合数据写入事件表。
我们建议您开启事件数据入库。如果关闭该配置，拉取到的数据将不会写入事件表，后续无法在事件分析中使用。
2.4 集成配置
集成配置用于定义 Airbridge Actuals Report 的取数和入库口径，包括指标、维度、时间粒度、日期范围、入库后的事件名和扩展参数。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 是否必填 | 含义 |
|---|---|---|---|
source | metrics | 是 | 需要拉取的指标列表 |
| group_by | 是 | 需要按哪些维度聚合数据 | |
| time_granularity | 是 | 时间粒度，当前仅支持 day | |
| 根配置 | date_range | 是 | 每次拉取的日期范围 |
| sink_event | event_name | 是 | 入库后的事件名，可以自定义 |
| extra_params | filters | 否 | Airbridge 筛选条件 |
| sorts | 否 | Airbridge 排序条件 |
{
"source": {
"metrics": [
"app_events",
"app_installs",
"impressions",
"impressions_channel",
"clicks_channel",
"cost_channel"
],
"group_by": [
"ad_account_id",
"campaign_id",
"ad_group_id",
"ad_creative_id",
"event_date",
"channel"
],
"time_granularity": "day"
},
"date_range": "0,1",
"sink_event": {
"event_tracking": true,
"event_name": "airbridge_event_data"
},
"extra_params": {}
}
2.4.1 指标配置
metrics 用于配置需要拉取的 Airbridge 指标。常见指标包括事件数、安装数、展示数、点击数、成本和收益等。
| 指标字段 | 含义 | 配置说明 |
|---|---|---|
| app_events | 应用内事件数 | 示例配置 |
| app_installs | 应用安装数 | 示例配置 |
| impressions | 展示数 | 示例配置 |
| impressions_channel | 渠道展示数 | 示例配置 |
| clicks_channel | 渠道点击数 | 示例配置 |
| cost_channel | 渠道成本 | 示例配置 |
| app_total_revenue | 应用总收益 | 可选配置 |
2.4.2 分组维度
group_by 用于配置报表聚合维度。Airbridge 响应中的 groupBys 会按请求中的 group_by 顺序返回。
| 分组维度 | 入库字段名 | 类型 | 配置说明 | 备注 |
|---|---|---|---|---|
| ad_account_id | ad_account_id | 字符串 | 示例配置 | 广告账号 ID |
| campaign_id | campaign_id | 字符串 | 示例配置 | 广告计划 ID |
| ad_group_id | ad_group_id | 字符串 | 示例配置 | 广告组 ID |
| ad_creative_id | ad_creative_id | 字符串 | 示例配置 | 广告创意 ID |
| event_date | event_date | 日期 | 示例配置 | 数据日期 |
| channel | channel | 字符串 | 示例配置 | 渠道 |
| platform | platform | 字符串 | 可选配置 | 平台 |
| event_type | event_type | 字符串 | 可选配置 | 事件类型 |
| event_source | event_source | 字符串 | 可选配置 | 事件来源 |
| event_category | event_category | 字符串 | 可选配置 | 事件分类 |
请勿在解析或入库时改变
group_by的顺序。 如果顺序发生变化，可能导致维度值错位。
2.4.3 扩展参数
Airbridge Actuals Report 支持筛选和排序。您可以在 extra_params 中配置 filters 和 sorts。
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| extra_params.filters | 否 | 筛选条件，dimension 必须属于 source.group_by |
| extra_params.sorts | 否 | 排序条件，fieldName 必须属于 source.group_by 或 source.metrics |
配置示例：
{
"extra_params": {
"filters": [
{
"dimension": "channel",
"filterType": "IN",
"values": [
"App"
]
}
],
"sorts": [
{
"fieldName": "event_date",
"isAscending": true
}
]
}
}
2.5 配置限制
| 模块 | 限制项 | 规则 |
|---|---|---|
| 定时拉取 | 单次查询时间窗口 | 最多 400 天 |
| 查询时间范围 | 最多 1000 天 | |
| 集成配置 | source.group_by | 最多 10 个 |
| source.metrics | 最多 20 个 | |
| extra_params.filters[].dimension | 必须属于 source.group_by | |
| extra_params.sorts[].fieldName | 必须属于 source.group_by 或 source.metrics |
2.6 事件入库规则
Airbridge Actuals Report 的报表结果不是平铺的字段对象，而是由 groupBys 和 values 共同组成。
- 由于 Actuals Report 返回的是聚合数据，因此会使用一个固定值作为用户标识，您可以认为所有数据挂载在一个虚拟用户上。
- 使用数据中的
event_date字段，即数据日期，设置为聚合数据的#event_time。 - 模板中使用的事件名为
airbridge_event_data。如需修改，请调整sink_event.event_name。 groupBys按请求中的source.group_by顺序返回。- 入库时会按相同顺序把
groupBys数组中的值写入对应维度字段。 values.<metric>.value会作为指标值写入事件属性。- 其余可识别的指标和维度字段均会入库。
- 如果指标返回
isMasked=true，表示该指标值被 Airbridge 脱敏或隐藏，分析时需要关注。 - 如果响应中存在
notifications，表示 Airbridge 对聚合结果进行了提示或处理，建议在排查数据差异时参考。
示例：
{
"groupBys": [
"2026-06-02",
"facebook.business",
"120239009297780452"
],
"values": {
"app_events": {
"value": 2,
"isMasked": false
}
}
}
如果请求中的 group_by 为 ["event_date", "channel", "campaign_id"]，则上述数据会映射为：
| 入库字段 | 入库值 |
|---|---|
| event_date | 2026-06-02 |
| channel | facebook.business |
| campaign_id | 120239009297780452 |
| app_events | 2 |
2.7 标准化字段
Airbridge 字段可按 AE 系统的广告标准对象 te_ads_object 进行标准化，但最终映射关系需要结合 Airbridge 字段语义和 AE 系统公共字段定义确认后再发布。
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| ad_account_id | te_ads_object.ad_account_id | 广告账号 ID |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| campaign | te_ads_object.campaign_name | 广告计划名称 |
| ad_group_id | te_ads_object.ad_group_id | 广告组 ID |
| ad_group | te_ads_object.ad_group_name | 广告组名称 |
| ad_creative_id | te_ads_object.ad_id | 广告 ID |
| ad_creative | te_ads_object.ad_name | 广告名 |
| channel | te_ads_object.media_source | 媒体来源 |
| platform | te_ads_object.platform | 平台 |
| country | te_ads_object.country | 国家地区 |
| currency | te_ads_object.currency | 币种 |
| agency_of_the_tracking_link_creator | te_ads_object.agency | 代理 |
| app_package_name | te_ads_object.app_id | 应用 ID |
| airbridge_app_name | te_ads_object.app_name | 应用名称 |
| impressions_channel | te_ads_object.impressions | 曝光 |
| clicks_channel | te_ads_object.clicks | 点击 |
| cost_channel | te_ads_object.cost | 广告成本 |
| app_installs | te_ads_object.installs | 安装 |
三、后续使用
3.1 数据入库检查
保存并启用方案后，您可以在 AE 系统中检查 sink_event.event_name 对应事件是否有数据入库。
3.2 单次拉取数据
如需临时补拉指定日期范围的数据，可以使用单次拉取能力。补拉时仍需遵守 Airbridge Actuals Report 的日期范围限制。
单次补拉的日期范围不能超过 400 天。
3.3 数据差异排查
如果 AE 系统中的数据与 Airbridge 后台展示不一致，建议优先检查以下配置：
date_range和拉取时区是否符合 Airbridge 报表口径。metrics和group_by是否与 Airbridge 后台报表选择一致。filters和sorts是否影响了返回结果。- 是否完整读取了分页结果。
- 返回结果中是否存在
isMasked=true或notifications。