# 巨量引擎广告升级版数据报表
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| 广告升级版数据报表 | API | 聚合数据 | ✅ | ✅ | ✅ | ✅ |
广告升级版数据报表 (opens new window)是巨量引擎新增的广告数据报表，可以拉取巨量广告升级版的投放数据。
# 集成流程
- 登录巨量引擎开放平台 (opens new window)，创建开发者账号与应用
- 获取应用的 APP_ID、Secret 以及登录用户 ID
- 登录 TE 后台，进入三方集成模块，新增巨量引擎广告升级版数据报表的集成方案
- 打开授权链接，并登录您需要拉取的广告账号所属的巨量账号，完成授权
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、获取授权信息
# 1.1 创建开发者账号与应用
在接入巨量引擎数据前，您需要申请巨量引擎开发者账号，并创建一个应用
首先您需要登录或注册巨量账号，点击本链接进入登录注册页 (opens new window)，如果您拥有巨量引擎账号，可选择左下角登陆，登陆对应账号；如果没有账号，则使用邮箱或手机号注册巨量引擎账号
完成登录后，您将跳转至巨量引擎开放平台 (opens new window)，点击页面右上角「开发者管理后台」按钮，进入开发者后台
如果您没有创建开发者账号，则此时需要您完成开发者信息的录入与资质审核，由于一个公司信息仅能注册认证一个开发者账户，请务必使用公司邮箱进行申请，并妥善保管该账号。具体的申请流程，可以参考官方文档 (opens new window)。
- 开发者类型，需要选择广告主/代理商，请按实际情况选择其一，两者的差异如下：
- 广告主：只可申请与开发者账户同公司主体的纵横组织账户授权
- 代理商：只可申请与开发者账户同公司主体的代理商账户授权
开发者账号认证通过后，请进入开发者官网并进入「APPID管理」页面，选择创建「广告管理」类型应用
- 应用名称、应用图表、应用描述可以按照实际需要进行编写，描述应用的作用是将巨量投放数据回传到自有平台
- 回调地址处，请填写「www.thinkingdata.cn」，该地址只是临时的地址，在方案配置完毕后还需要调整
- 申请权限出，至少需要选中「数据报表」权限
申请提交后，巨量将在一个工作日内审核完成您的应用创建（APPID）申请
# 1.2 获取 App ID、App Secret
完成应用申请后，请进入到开发者后台，从左边栏找到「应用管理」-「基础应用」，选择创建的应用，点击「编辑」进入「基本信息」页面，找到 APP_ID 和 Secret，并记录下来。
# 1.3 获取登录用户 ID
接下来，您需要获得登录用户的 ID。请进入到「巨量引擎开发平台」，点击右上角"六边形标识"，点击「巨量纵横」进入后台，点击右上角「账户信息与安全」，找到登录用户 ID，并记录下来
# 1.4 总结
至此，您已经获得了所有需要的授权信息。此时您应该获得了以下信息：
- App ID
- App Secret
- 登录用户 ID
# 二、方案配置
当您获得了所有授权信息后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是巨量引擎广告升级版数据报表的配置界面，请您按照本章节内容完成方案的创建：
# 2.1 授权信息配置
点击「授权信息」按钮，在弹出框内填写您在上一步中获得的信息：
其中：
- APP ID：应用的 APP ID
- APP Secret：应用的 APP Secret
- Login ID：登录用户 ID
- Account ID List：需要拉取数据的广告账号 ID，如果不填写则会拉取授权用户下的所有广告账号的数据
# 2.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取巨量引擎广告升级版数据报表的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
# 2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义，字符串类型。接收到的数据均将以该名称作为事件名。 |
| source | metrics | 数据中的指标，列表类型，可以自定义 |
| group_by | 数据中的分组维度，列表类型，可以自定义 | |
| time_granularity | 数据的时间聚合粒度，即拉取的数据以天还是小时进行聚合 可选值: day、hour |
您可以按照需要，对集成配置进行修改
# 2.4.1 分析维度
以下展示的是广告升级版数据报表支持的维度，请注意，小时粒度与部分维度互斥。如需添加其他分析维度，可以将字段名写入 source.group_by 中
| 字段名 | 中文名 | 默认 | 备注 |
|---|---|---|---|
| advertiser_id（必有，不用填写） | 广告账号 ID | 是 | |
| cdp_project_id | 项目ID | 是 | |
| cdp_project_name | 项目名称 | 是 | |
| cdp_promotion_id | 广告ID | 是 | |
| cdp_promotion_name | 广告名称 | 是 | |
| package_name | 包名 | 是 | |
| 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 | 深度转化出价 | ||
| ad_platform_cdp_promotion_roi_goal | ROI系数 | ||
| app_code | 首选位置 |
# 2.4.2 涵盖指标
以下表格展示的是广告升级版数据报表支持的部分常用指标，由于全量指标过多，此处无法完全展示。如需添加其他指标，可以将指标名写入 source.metrics 中
| 指标名 | 中文名 | 默认 | 备注 |
|---|---|---|---|
| stat_cost | 消耗 | 是 | |
| show_cnt | 展示数 | 是 | |
| cpm_platform | 平均千次展现费用 | 是 | |
| click_cnt | 点击数 | 是 | |
| ctr | 点击率 | 是 | |
| cpc_platform | 平均点击单价 | 是 | |
| convert_cnt | 转化数 | 是 | |
| conversion_cost | 平均转化成本 | 是 | |
| conversion_rate | 转化率 | 是 | |
| deep_convert_cnt | 深度转化数 | ||
| deep_convert_cost | 深度转化成本 | ||
| deep_convert_rate | 深度转化率 | ||
| active | 激活数 | 是 | |
| active_cost | 激活成本 | 是 | |
| active_rate | 激活率 | 是 | |
| active_register | 注册数 | 是 | |
| active_register_cost | 注册成本 | 是 | |
| active_register_rate | 注册率 | 是 | |
| game_addiction | 关键行为数 | ||
| game_addiction_cost | 关键行为成本 | ||
| game_addiction_rate | 关键行为率 | ||
| total_play | 播放量 | 是 | |
| valid_play | 有效播放数 | 是 | |
| valid_play_cost | 有效播放成本 | 是 | |
| valid_play_rate | 有效播放率 | 是 | |
| valid_play_of_mille | 千次有效播放数 | 是 | |
| valid_play_cost_of_mille | 千次有效播放成本 | 是 | |
| play_25_feed_break | 25%进度播放数 |
与以下分析维度不兼容：
| |
| play_50_feed_break | 50%进度播放数 | ||
| play_75_feed_break | 75%进度播放数 | ||
| play_99_feed_break | 99%进度播放数 | ||
| average_play_time_per_play | 平均单次播放时长 | ||
| play_over_rate | 完播率 | ||
| wifi_play_rate | WiFi播放占比 | ||
| card_show | 3秒卡片展现数 | ||
| play_duration_3s | 3秒播放数 |
# 2.4.3 数据入库规则
- 使用数据中的 dimensions_stat_time_hour 或 dimensions_stat_time_day 字段，即数据的日期，设置为聚合数据的 #event_time
- 数据事件名为 -- oceanengine_custom_data
- 其余字段都将会入库
# 2.5 完成授权
完成配置后，您可以点击右上角的「保存并授权」将方案配置保存下来。接下来，您需要完成最后的授权工作：
首先，请在弹出的「授权信息」页面中，将第一步中的地址复制下来
回到巨量引擎开发者后台，进入到之前创建的应用的基础信息页，将刚刚复制的地址填入回调地址处
再回到 TE 界面，点击「前往授权」，此时将打开巨量引擎的授权页面
此时将展示授权界面，选择「当前用户全量账户」，并确认「当前登录用户」拥有您需要拉取数据的广告账户。请确认红框中的登录用户 ID 是您在方案配置中输入的登录用户 ID。确认完毕后，点击同意授权，即可完成授权工作。
完成了授权之后，请在「授权信息」中点击左下角的「我已完成以上两步操作」后点击右下角的「完成授权」结束配置。至此，您完成巨量引擎广告创意数据的集成。
# 2.6 标准化字段
巨量引擎多合一数据报表中的部分字段，TE 系统会进行标准化处理：
| 字段名 | 标准化字段 | 含义 |
|---|---|---|
| advertiser_id | te_ads_object.ad_account_id | 广告主 ID |
| cdp_project_id | te_ads_object.ad_group_name | 广告计划名称 |
| cdp_project_name | te_ads_object.ad_group_id | 广告计划 ID |
| cdp_promotion_id | te_ads_object.ad_name | 创意名 |
| cdp_promotion_name | te_ads_object.ad_id | 创意 ID |
| package_name | te_ads_object.app_name | 应用名 |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| 【CNY】（定值） | te_ads_object.currency | 成本或收益的币种 |
| show_cnt | te_ads_object.impressions | 展示数 |
| click_cnt | te_ads_object.clicks | 点击数 |
| convert_cnt | te_ads_object.installs | 点击安装数 |
| stat_cost | te_ads_object.cost | 总消耗 |