巨量引擎数据集成方案
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
概要
本文将介绍如何将巨量引擎数据回传到 Agentic Engine（后文简称 AE 系统） ，本方案支持：
- 获取 多合一数据报表 的聚合指标数据，其中包含消耗、点击、展示等基础报表指标，并按广告账号、广告组、广告计划和素材维度分组
- 获取 广告创意数据 的聚合指标数据，其中包含消耗、点击、展示等基础报表指标，并按广告账号、广告组、广告计划和素材维度分组
- 获取 广告升级版数据报表 的聚合指标数据，也就是新版巨量广告的数据报表。其中包含消耗、点击、展示等基础报表指标，并按广告账号、广告组、广告计划和素材维度分组
本文主要介绍的是通过底层 API 的方式将数据接入到 AE 系统，如果您希望了解在产品后台进行配置，请参考本产品文档。
在开始接入巨量引擎数据前，请确保您已经阅读 AE 系统数据规则，理解 AE 的数据结构。另外，建议您将拉取数据所需的信息交给我们的客户成功经理，格式可参考数据集成配置信息模板。
流程
巨量引擎数据的接入流程如下：
- 登录巨量引擎开放平台，创建开发者账号与应用，将应用的 APP_ID 与 Secret、登录用户 ID 发送给 AE 工作人员
- 在应用管理页面的回调地址处，填入 AE 工作人员提供的地址
- 打开授权链接，并登录您需要拉取的广告账号所属的巨量账号，完成授权
- 确定数据拉取的数据维度、指标类型、拉取频率以及拉取时间范围
- 由 AE 工作人员完成数据拉取开发工作
- 在 AE 后台搭建看板、报表，并完成数据验收
二、集成前准备工作
2.1 创建开发者账号与应用
在接入巨量引擎数据前，您需要申请巨量引擎开发者账号，并创建一个应用
- 首先您需要登录或注册巨量账号，点击本链接进入登录注册页，如果您拥有巨量引擎账号，可选择左下角登陆，登陆对应账号；如果没有账号，则使用邮箱或手机号注册巨量引擎账号
- 完成登录后，您将跳转至巨量引擎开放平台，点击页面右上角「开发者管理后台」按钮，进入开发者后台
-
如果您没有创建开发者账号，则此时需要您完成开发者信息的录入与资质审核，由于一个公司信息仅能注册认证一个开发者账户，请务必使用公司邮箱进行申请，并妥善保管该账号。具体的申请流程，可以参考官方文档。
- 开发者类型，需要选择广告主/代理商，请按实际情况选择其一，两者的差异如下：
- 广告主：只可申请与开发者账户同公司主体的纵横组织账户授权
- 代理商：只可申请与开发者账户同公司主体的代理商账户授权
- 开发者账号认证通过后，请进入开发者官网并进入「APPID管理」页面，选择创建「广告管理」类型应用
- 请注意，在创建时的权限范围中，需要选中「数据报表」权限
- 申请提交后，巨量将在一个工作日内审核完成您的应用创建（APPID）申请
2.2 获取 App ID、App Secret
完成应用申请后，请进入到开发者后台，从左边栏找到「应用管理」-「基础应用」，选择创建的应用，点击「编辑」进入「基本信息」页面，找到 APP_ID 和 Secret，将其发送给 AE 工作人员。
2.3 获取登录用户 ID 并完成授权
接下来，请进入到「巨量引擎开放平台」，点击右上角"六边形标识"，点击「巨量纵横」进入后台，点击右上角「账户信息与安全」，找到登录用户 ID，并将登录用户 ID 提供给 AE 工作人员。
提供登录用户 ID 后，AE 工作人员将会给您提供回调地址，请在应用编辑页面的「回调地址」处中填入该地址。
填写完毕后，您可以在页面底部看到授权 URL。将其复制到浏览器中并打开。
此时将展示授权界面，选择「当前用户全量账户」，并确认「当前登录用户」拥有您需要拉取数据的广告账户。请确认红框中的登录用户 ID 是您之前提供给 AE 工作人员的登录用户 ID。确认完毕后，点击同意授权，即可完成授权工作。
三、数据拉取
巨量引擎提供了一系列广告数据报表，AE 目前支持拉取多合一数据报表、广告创意数据以及广告升级版数据报表。
3.1 多合一数据报表
接口基本信息
| 接口名 | API 类型 | 产品化 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|---|
| 多合一数据报表接口 | 拉式 | 是 | 聚合数据 | 是 | 是 | 是 | 是 |
多合一数据报表支持拉取各广告粒度、素材、关键词层级的数据，因此其分析维度最为丰富，但支持的指标相对普通数据报表要少一些。总的来说，是最为常用的数据报表。
3.1.1 分析维度
以下表格是多合一数据报表支持的分析维度，我们默认的分组条件是：
- STAT_GROUP_BY_TIME_HOUR
- STAT_GROUP_BY_CREATIVE_ID
如需进行调整，请先查看分组组合规则，并将需要调整的内容记录在数据集成配置信息模板中：
| 字段名 | 含义 | 分组条件 | 是否默认 |
|---|---|---|---|
| stat_datetime | 时间 | STAT_GROUP_BY_TIME_MONTH STAT_GROUP_BY_TIME_WEEK STAT_GROUP_BY_TIME_DAY STAT_GROUP_BY_TIME_HOUR | 是 |
advertiser_id | 广告主 ID | STAT_GROUP_BY_ADVERTISER_ID STAT_GROUP_BY_CAMPAIGN_ID STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | 是 |
| campaign_name | 广告组名称 | STAT_GROUP_BY_CAMPAIGN_ID STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | 是 |
| campaign_id | 广告组 ID | 是 | |
| ad_name | 广告计划名称 | STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | 是 |
| ad_id | 广告计划 ID | 是 | |
| creative_id | 创意 ID | STAT_GROUP_BY_CREATIVE_ID | 是 |
| bidword | 关键词名称 | STAT_GROUP_BY_BIDWORD_ID | |
| bidword_id | 关键词 ID | ||
| query | 搜索词 | STAT_GROUP_BY_QUERY | |
| pricing | 出价方式 | STAT_GROUP_BY_PRICING | |
| image_mode | 素材类型 | STAT_GROUP_BY_IMAGE_MODE | |
| inventory | 广告首选位置 | STAT_GROUP_BY_INVENTORY | |
| campaign_type | 广告组类型 | STAT_GROUP_BY_CAMPAIGN_TYPE | |
| creative_material_mode | 创意类型 | STAT_GROUP_BY_CREATIVE_MATERIAL_MODE | |
| external_action | 转化类型 | STAT_GROUP_BY_EXTERNAL_ACTION | |
| landing_type | 推广类型 | STAT_GROUP_BY_LANDING_TYPE | |
| pricing_category | 广告类型 | STAT_GROUP_BY_PRICING_CATEGORY | |
| province_name | 省份 | STAT_GROUP_BY_PROVINCE_NAME | |
| city_name | 城市 | 同时包含 STAT_GROUP_BY_CITY_NAME 与 STAT_GROUP_BY_PROVINCE_NAME | |
| gender | 性别 | STAT_GROUP_BY_GENDER | |
| age | 年龄 | STAT_GROUP_BY_AGE | |
| platform | 平台 | STAT_GROUP_BY_PLATFORM | |
| ac | 网络类型 | STAT_GROUP_BY_AC | |
| material_id | 素材ID | STAT_GROUP_BY_MATERIAL_ID | |
| playable_id | 试玩素材ID | STAT_GROUP_BY_PLAYABLE_ID | |
| playable_name | 试玩素材名称 | ||
| playable_url | 试玩素材链接 | ||
| playable_orientation | 试玩素材展示方向 | ||
| playable_preview_url | 试玩素材预览链接 |
3.1.2 涵盖指标
以下表格展示的是多合一数据报表支持的部分常用指标，由于全量指标过多，此处无法完全展示，如有需要，可以访问官方文档获取全指标说明：
| 指标名 | 中文名 | 是否默认 |
|---|---|---|
| active | 激活数 | 是 |
| active_cost | 激活成本 | 是 |
| active_pay_cost | 首次付费成本 | 是 |
| active_pay_rate | 首次付费率 | 是 |
| active_rate | 激活率 | 是 |
| active_register_cost | 注册成本 | 是 |
| active_register_rate | 注册率 | 是 |
| attribution_active_pay_7d_per_count | 7日人均付费次数 | 是 |
| attribution_convert | 转化数（计费时间） | 是 |
| attribution_convert_cost | 转化成本（计费时间） | 是 |
| attribution_deep_convert | 深度转化数（计费时间） | 是 |
| attribution_deep_convert_cost | 深度转化成本（计费时间） | 是 |
| attribution_game_pay_7d_cost | 7日付费成本 | |
| attribution_game_pay_7d_count | 7日付费次数 | |
| attribution_next_day_open_cnt | 次留数 | |
| attribution_next_day_open_cost | 次留成本 | |
| attribution_next_day_open_rate | 次留率 | |
| avg_click_cost | 平均点击单价 | 是 |
| avg_show_cost | 平均千次展现费用 | 是 |
| click | 点击数 | 是 |
| click_install | 点击安装数 | 是 |
| convert | 转化数 | 是 |
| convert_cost | 转化成本 | 是 |
| convert_rate | 转化数据-转化率 | 是 |
| cost | 总消耗 | 是 |
| ctr | 点击率 | 是 |
| deep_convert | 深度转化数 | 是 |
| deep_convert_cost | 深度转化成本 | 是 |
| deep_convert_rate | 深度转化率 | 是 |
| download | 下载开始 | 是 |
| game_addiction | 关键行为数 | 是 |
| game_addiction_cost | 关键行为成本 | 是 |
| game_addiction_rate | 关键行为率 | 是 |
| game_pay_cost | 付费成本 | 是 |
| game_pay_count | 付费次数 | 是 |
| next_day_open | 次留回传数（未对回） | |
| next_day_open_cost | 次留成本（未对回） | |
| next_day_open_rate | 次留率（未对回） | |
| pay_count | 首次付费次数 | 是 |
| play_100_feed_break | 99%进度播放数 | |
| play_25_feed_break | 25%进度播放数 | |
| play_50_feed_break | 50%进度播放数 | |
| play_75_feed_break | 75%进度播放数 | |
| play_duration_sum | 播放时长，单位ms | |
| total_play | 播放数 | |
| valid_play | 有效播放数 | |
| valid_play_cost | 有效播放成本 | |
| valid_play_rate | 有效播放率 | |
| play_over_rate | 播完率 | |
| redirect | 页面跳转 | |
| register | 注册数 | |
| share | 分享数 | |
| show | 展示数 | 是 |
| wifi_play | WiFi播放量 | |
| wifi_play_rate | WiFi播放占比 |
3.1.3 接口参数
-
广告账号：
- 需要指定拉取的数据的广告账号
-
时间：
-
拉取以日为时间单位的数据
- 对于搜索词报表，只支持查看最近 30 天的数据
- 对于关键词报表，只支持查看 2019-05-19 之后的数据
- 对于所有报表，时间跨度不得超过30天
-
数据可按天或按小时聚合，默认为按小时
-
3.1.4 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：
- 由于多合一报表返回的数据为聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 stat_datetime 字段，即数据的日期，设置为聚合数据的 #event_time
- 数据事件名为 -- oceanengine_show_click_convert_data
- 其余字段都将会入库
3.2 广告创意数据
广告创意数据是广告数据粒度最细的普通数据报表，相比多合一数据报表来说，分析维度较少，但是支持的指标会多一些。
接口基本信息
| 接口名 | API 类型 | 产品化 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|---|
| 广告创意数据 | 拉式 | 否 | 聚合数据 | 是 | 是 | 是 | 是 |
3.2.1 分析维度
以下表格是广告创意数据报表支持的分析维度，我们默认的分组条件是：
- STAT_GROUP_BY_FIELD_STAT_TIME
- STAT_GROUP_BY_FIELD_ID
除此之外，您还可以增加最多一个其他分组条件（比如下表中的 STAT_GROUP_BY_INVENTORY），也可不添加，即采用默认分组条件
如需进行调整，请将需要调整的内容记录在数据集成配置信息模板中：
| 字段名 | 含义 | 分组条件 | 是否默认 |
|---|---|---|---|
| stat_datetime | 数据起始时间，格式为：
| STAT_GROUP_BY_FIELD_STAT_TIME | 是 |
| advertiser_id | 广告主 ID | STAT_GROUP_BY_FIELD_ID | 是 |
| campaign_name | 广告组名称 | 是 | |
| campaign_id | 广告组 ID | 是 | |
| ad_name | 广告计划名称 | 是 | |
| ad_id | 广告计划 ID | 是 | |
| creative_id | 创意 ID | 是 | |
| inventory | 投放广告位 | STAT_GROUP_BY_INVENTORY | |
| creative_material_mode | 创意类型，取值：
| STAT_GROUP_BY_CREATIVE_MATERIAL_MODE | |
| landing_type | 推广目的类型 | STAT_GROUP_BY_LANDING_TYPE | |
| pricing | 出价类型 | STAT_GROUP_BY_PRICING | |
| image_mode | 素材类型 | STAT_GROUP_BY_IMAGE_MODE | |
| province_name | 省份 | STAT_GROUP_BY_PROVINCE_NAME | |
| city_name | 城市 | STAT_GROUP_BY_CITY_NAME | |
| gender | 性别 | STAT_GROUP_BY_GENDER | |
| age | 年龄 | STAT_GROUP_BY_AGE | |
| platform | 平台 | STAT_GROUP_BY_PLATFORM | |
| ac | 类型 | STAT_GROUP_BY_AC |
3.2.2 涵盖指标
以下表格展示的是广告创意数据报表支持的部分常用指标，由于全量指标过多，此处无法完全展示，如有需要，可以访问官网文档获取全指标说明：
| 指标名 | 中文名 | 是否默认 |
|---|---|---|
| active | 激活数 | 是 |
| active_cost | 激活成本 | 是 |
| active_pay_cost | 首次付费成本 | 是 |
| active_pay_rate | 首次付费率 | 是 |
| active_rate | 激活率 | 是 |
| active_register_cost | 注册成本 | 是 |
| active_register_rate | 注册率 | 是 |
| attribution_active_pay_7d_per_count | 7日人均付费次数 | 是 |
| attribution_convert | 转化数（计费时间） | 是 |
| attribution_convert_cost | 转化成本（计费时间） | 是 |
| attribution_deep_convert | 深度转化数（计费时间） | 是 |
| attribution_deep_convert_cost | 深度转化成本（计费时间） | 是 |
| attribution_game_pay_7d_cost | 7日付费成本 | |
| attribution_game_pay_7d_count | 7日付费次数 | |
| attribution_next_day_open_cnt | 次留数 | |
| attribution_next_day_open_cost | 次留成本 | |
| attribution_next_day_open_rate | 次留率 | |
| avg_click_cost | 平均点击单价 | 是 |
| avg_show_cost | 平均千次展现费用 | 是 |
| click | 点击数 | 是 |
| click_install | 点击安装数 | 是 |
| convert | 转化数 | 是 |
| convert_cost | 转化成本 | 是 |
| convert_rate | 转化数据-转化率 | 是 |
| cost | 总消耗 | 是 |
| ctr | 点击率 | 是 |
| deep_convert | 深度转化数 | 是 |
| deep_convert_cost | 深度转化成本 | 是 |
| deep_convert_rate | 深度转化率 | 是 |
| download | 下载开始 | 是 |
| game_addiction | 关键行为数 | 是 |
| game_addiction_cost | 关键行为成本 | 是 |
| game_addiction_rate | 关键行为率 | 是 |
| game_pay_cost | 付费成本 | 是 |
| game_pay_count | 付费次数 | 是 |
| next_day_open | 次留回传数（未对回） | |
| next_day_open_cost | 次留成本（未对回） | |
| next_day_open_rate | 次留率（未对回） | |
| pay_count | 首次付费次数 | 是 |
| play_100_feed_break | 99%进度播放数 | |
| play_25_feed_break | 25%进度播放数 | |
| play_50_feed_break | 50%进度播放数 | |
| play_75_feed_break | 75%进度播放数 | |
| play_duration_sum | 播放时长，单位ms | |
| total_play | 播放数 | |
| valid_play | 有效播放数 | |
| valid_play_cost | 有效播放成本 | |
| valid_play_rate | 有效播放率 | |
| play_over_rate | 播完率 | |
| redirect | 页面跳转 | |
| register | 注册数 | |
| share | 分享数 | |
| show | 展示数 | 是 |
| wifi_play | WiFi播放量 | |
| wifi_play_rate | WiFi播放占比 |
3.2.3 接口参数
- 广告账号：
- 需要指定拉取的数据的广告账号
- 时间：
- 拉取以日为时间单位的数据
- 时间跨度不能超过30天
- 拉取以日为时间单位的数据
3.2.4 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：
- 由于广告创意报表返回的数据为聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 stat_datetime 字段，即数据的日期，设置为聚合数据的 #event_time
- 数据事件名为 -- oceanengine_creative_data
- 其余字段都将会入库
3.3 广告升级版数据报表
接口基本信息
| 接口名 | API 类型 | 产品化 | 数据粒度 | 归因数据 | 成本数据 | 收益数据 | 展示数据 | 点击数据 | 转化数据 |
|---|---|---|---|---|---|---|---|---|---|
| 广告升级版数据报表 | 拉式 | 否 | 聚合数据 | 是 | 是 | 是 | 是 |
广告升级版数据报表是巨量引擎新增的广告数据报表，可以拉取巨量广告升级版的投放数据。
3.3.1 分析维度
以下展示的是广告升级版数据报表支持的维度，您可以选择「天级别」与「小时级别」报表。请注意，小时级报表与部分维度互斥
| 明细 | 字段名 | 天级别默认 | 小时级别默认 | 标准化字段 | 备注 |
|---|---|---|---|---|---|
| 广告账号 ID | - | 是 | 是 | ad_account_id | |
时间 | stat_time_day（天级别） stat_time_hour（小时级别） | 是 | 是 | 小时级报表不可用以下维度
| |
| 项目ID | cdp_project_id | 是 | 是 | ad_group_id | |
| 项目名称 | cdp_project_name | 是 | 是 | ad_group_name | |
| 广告ID | cdp_promotion_id | 是 | 是 | ad_id | |
| 广告名称 | cdp_promotion_name | 是 | 是 | ad_name | |
| 包名 | package_name | 是 | 是 | app_name | |
| 平台 | platform | 是 | platform | 与以下维度互斥
小时级报表不可用 | |
| 性别 | gender | ||||
| 年龄 | age | ||||
| 网络 | ac | ||||
| 省份 | province_name | 与以下维度互斥
小时级报表不可用 | |||
| 城市 | city_name | ||||
| 素材类型 | image_mode | ||||
| 推广目的 | landing_type | ||||
| 转化目标 | external_action | ||||
| 计费类型 | pricing | ||||
| 深度转化目标 | deep_external_action | ||||
| 下载方式 | ad_platform_cdp_project_download_type | ||||
| 下载链接 | ad_platform_cdp_project_download_url | ||||
| 转化监测地址 | ad_platform_cdp_project_action_track_url | ||||
| 投放模式 | delivery_mode | ||||
| 广告出价 | ad_platform_cdp_promotion_bid | ||||
| 深度转化出价 | ad_platform_cdp_promotion_deep_cpa_bid | ||||
| ROI系数 | ad_platform_cdp_promotion_roi_goal | ||||
| 首选位置 | app_code |
3.3.2 涵盖指标
以下表格展示的是广告升级版数据报表支持的部分常用指标，由于全量指标过多，此处无法完全展示
| 指标 | 指标名 | 描述 | 默认 | 标准化字段 | 备注 |
|---|---|---|---|---|---|
| 消耗 | stat_cost | 表示广告在投放期内的预估花费金额。当天数据可能会有波动，次日稳定 | 是 | cost | |
| 展示数 | show_cnt | 广告展示给用户的次数。计算方式：经平台判定有效且被计费的展示次数。 | 是 | impressions | |
| 平均千次展现费用 | cpm_platform | 广告平均每一千次展现所付出的费用，计算公式是：总消耗/展示数*1000。 | 是 | ||
| 点击数 | click_cnt | 当用户点击广告素材时，触发点击事件，该事件被认为是一次有效的广告点击。 | 是 | clicks | |
| 点击率 | ctr | 广告被点击的次数占展示次数的百分比。计算方法：点击数/展示数*100% | 是 | ||
| 平均点击单价 | cpc_platform | 广告主为每次点击付出的费用成本，计算公式是：总消耗/点击数。 | 是 | ||
| 转化数 | convert_cnt | 按转化事件发生时间统计的转化数。建议广告主考核成本时参考“转化数据(计费时间)”，例如您的广告在早上8点进行了展示和点击，用户晚上19点发生了激活行为，巨量引擎会把激活数计在晚上19点。 | 是 | installs | |
| 平均转化成本 | conversion_cost | 广告主为每个转化所付出的平均成本，计算方式：总消耗/转化数。当天数据可能会有波动。 | 是 | ||
| 转化率 | conversion_rate | 广告被用户转化的次数占点击次数的百分比。计算方式：转化数/点击数*100% | 是 | ||
| 深度转化数 | deep_convert_cnt | 将深度转化数记录在转化事件发生的时间上。建议广告主考核深度转化成本时参考“深度转化数（计费时间）”例如您的广告在早上8点进行了展示和点击，用户晚上19点发生了激活行为，巨量引擎会把激活数计在晚上19点。 | |||
| 深度转化成本 | deep_convert_cost | 广告主为每个深度转化所付出的平均成本，计算方法：总消耗/深度转化数。当天数据可能会有波动，次日早8点后稳定。 | |||
| 深度转化率 | deep_convert_rate | 广告被用户进行深度转化的次数占转化次数的百分比。计算方式：深度转化数/转化数*100% | |||
| 激活数 | active | 如果您对接了API，激活数是您认可且回传成功的激活数。如果您对接了SDK，则激活数是指用户下载您的APP后打开的次数。 | 是 | ||
| 激活成本 | active_cost | 计算方式：总花费/激活数。 | 是 | ||
| 激活率 | active_rate | 计算方式：激活数/点击数*100% | 是 | ||
| 注册数 | active_register | 如果您对接了API，注册数是您认可且回传成功的注册数。如果您对接了SDK，则注册数是用户实现注册行为的次数，详情见「SDK对接文档」 | 是 | ||
| 注册成本 | active_register_cost | 广告主为每个注册所付出的成本，计算公式是：总花费/注册数，当天数据可能会有波动，次日早8点后稳定。 | 是 | ||
| 注册率 | active_register_rate | 注册用户占激活用户的比例 | 是 | ||
| 关键行为数 | game_addiction | 有APP内关键行为的用户数量 | |||
| 关键行为成本 | game_addiction_cost | 广告主为每个有APP内关键行为的用户所付出的成本，计算公式是总花费/关键行为数。当天数据可能会有波动，次日早8点后稳定。 | |||
| 关键行为率 | game_addiction_rate | 关键行为用户占激活用户的比例 | |||
| 播放量 | total_play | 播放时间大于0S的数量，在某些蜂窝网络环境下，需要您手动点击开始才会开始播放，因此有时播放数小于展示数。 | 是 | ||
| 有效播放数 | valid_play | 竞价广告播放时间大于等于10秒的数量，如果视频总时长不足10秒，则记录播放完成的次数。品牌广告在部分APP（头条、头条lite、抖音、西瓜、抖音火山版、皮皮虾）播放时间大于等于5秒的数量，在其他APP大于等于3秒的数量，如果视频总时长不足5秒/3秒时，则记录播放完成的次数。 | 是 | ||
| 有效播放成本 | valid_play_cost | 计算公式：总花费/有效播放数，当天数据可能会有波动，次日早8点后稳定。 | 是 | ||
| 有效播放率 | valid_play_rate | 计算公式：有效播放数/展示数。 | 是 | ||
| 千次有效播放数 | valid_play_of_mille | 有效播放数/1000，其中有效播放数是指，竞价广告播放时间大于等于 10 秒的数量，如果视频总时长不足 10 秒，则记录播放完成的次数；品牌广告在部分 APP（头条、头条 lite、抖音、西瓜、抖音火山版、皮皮虾）播放时间大于等于 5s 的数量，在其他 APP 大于等于 3s 的数量，如果视频总时长不足 5s/3s 时，则记录播放完成的次数。 | 是 | ||
| 千次有效播放成本 | valid_play_cost_of_mille | 总花费/千次有效播放数，当天数据可能会有波动，次日早 8 点后稳定。 | 是 | ||
| 25%进度播放数 | play_25_feed_break | 用户播放至视频长度25%及以上的次数，包括跳跃播放至此长度的播放次数 | 不兼容的维度：
| ||
| 50%进度播放数 | play_50_feed_break | 用户播放至视频长度50%及以上的次数，包括跳跃播放至此长度的播放次数 | |||
| 75%进度播放数 | play_75_feed_break | 用户播放至视频长度75%及以上的次数，包括跳跃播放至此长度的播放次数 | |||
| 99%进度播放数 | play_99_feed_break | 用户播放至视频长度99%及以上的次数，包括跳跃播放至此长度的播放次数 | |||
| 平均单次播放时长 | average_play_time_per_play | 计算方法：视频播放总实际时长／播放总次数（不包含跳跃的时长） | |||
| 完播率 | play_over_rate | 计算公式：播放完成数/播放数。 | |||
| WiFi播放占比 | wifi_play_rate | 在wifi环境下视频的播放数/视频播放总数 | |||
| 3秒卡片展现数 | card_show | 对于视频卡片类广告，在视频播放到3秒时进行卡片展现的数量。 | |||
| 3秒播放数 | play_duration_3s | 广告播放时间大于等于3秒的数量，如果视频总时长不足3秒，则记录播放完成的次数。 |
3.3.3 接口参数
- 广告账号：
- 需要指定拉取的数据的广告账号
- 时间：
- 可选择天级别报表或小时级别报表
3.3.4 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：
- 由于广告升级版数据报表返回的数据为聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 使用数据中的 dimensions_stat_time_hour 或 dimensions_stat_time_day 字段，即数据的日期，设置为聚合数据的 #event_time
- 数据事件名为 -- oceanengine_custom_data
- 其余字段都将会入库
四、数据集成配置信息模板
在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在 ThinkingAI 的客户成功经理：
接口：巨量引擎广告数据报表
---------
公司名称：XXX
AE 项目环境：（SAAS/私有化）
AE 项目名称：XXX
AE 项目 APP ID: XXX
数据接收地址 push_url: XXX
---------
巨量引擎应用 APP_ID：XXX
巨量引擎应用 Secret: XXX
广告主（广告账号）ID 列表：XXX，XXX
登录用户 ID：XXXXXXXXX
---------
拉取的数据类型：[多合一/广告创意/升级版数据报表]
分析维度：XXX，XXX（不填意为默认）
需要拉取的字段：XXX，XXX（不填意为默认）
历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
拉取粒度：天级别（仅升级版数据报表支持小时级别）
定时拉取：每天 X 点拉取前 N 天的数据（每小时拉取 N 天的数据）
五、联调测试
可以在 AE 系统后台的「数据管理」-> 「事件管理」页面或 SQL IDE 页面搜索
- oceanengine_show_click_convert_data
或
- oceanengine_creative_data
或
- oceanengine_custom_data
事件并查看是否有相应数据入库
六、FAQ
我们同一个游戏不在一个巨量主体投放的话，能拉取数据么？
可以的。一个 AE 项目可以对应多个巨量 Token，支持将不同巨量用户下的投放数据汇总到同一个 AE 项目。为了拉取所有巨量主体的数据，您需要对每个巨量用户进行授权操作，并在 AE 平台巨量三方集成配置中添加多个集成方案。
我在巨量引擎后台新建应用，填写应用申请的时候，「回调地址」填什么？
新建应用时「回调地址」可以先填您公司的域名；添加完APP后，后续回调地址还可以再改为 AE 集群的巨量引擎回调地址。
我在巨量引擎后台无法找到登录用户ID？
可以通过两种方式在巨量引擎后台确认登录用户ID。
- 方式一：「巨量引擎开放平台」- 右上角点击"六边形标识"，点击「巨量纵横」-点击右上角「账户信息与安全」，找到登录用户ID。
- 方式二：「巨量引擎开放平台」-「开发者管理后台」-「应用管理」-「应用编辑」中，填写AE 系统回调地址-选择「数据报表」权限范围后 - 点击「授权URL」- 选择「当前用户全量账户」，可获取登录用户ID。
如何获取不同登录用户下的广告主ID/广告账户ID？
「巨量引擎开放平台」- 右上角点击"六边形标识"，点击「巨量广告平台」即可显示对应登录用户下的广告账户ID。(若没有「账户ID」，可点击「自定义列」添加「账户ID」)
为什么我填入了 advertiser_id 但是没有数据拉回？
您填写的可能是纵横组织的广告账户ID，我们需要填写纵横组织下的投放的广告账号ID，可以根据以下方式获取：
curl --location --request GET 'https://ad.oceanengine.com/open_api/2/majordomo/advertiser/select/?advertiser_id={纵横组织广告账号ID}' \
--header 'Access-Token:{ACCESS_TOKEN}' \
--header 'Content-Type:application/x-www-form-urlencoded' \
--data-urlencode 'advertiser_id={纵横组织广告账号ID}'
如何获取到同一纵横组织下面，不同登陆用户对应的广告主ID列表？
- 在巨量纵横页面右侧查看纵横组织ID；
- 使用「获取纵横组织下资产账户列表」接口，可以获取到纵横组织下面，不同登陆用户对应的广告主ID列表