# Tiktok Basic Report
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Basic Report | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
Tiktok Basic Report 提供了广告维度的聚合分组，返回数据中涵盖展示、点击、转化、买量成本等一系列指标数据。
# 集成流程
- 登录 Tikitok API Business 平台，注册开发者账号，创建应用并获取授权信息
- 登录 TE 后台，进入三方集成模块，新增 Tiktok Basic Report 方案，并完成相关配置
- 修改 Tiktok API 应用的授权地址并完成授权工作
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、获取授权信息
首先，您需要访问 Tiktok API Business 页面 (opens new window)，需要登录或注册一个TikTok 广告账号
接下来，按照步骤注册成为开发者
注册成为开发者后，您需要创建一个应用，如下图所示。创建时的参数，可以按如下方式配置：
- Application name：项目名，按照您的项目为其命名
- App Description：项目描述，可以添加一些备注信息
- Callback Address：回调地址，在创建时可以填写 https://www.thinkingdata.cn/，之后再改为 TE 系统的数据回调地址
- Scope of Permission：可访问的数据权限，此处请务必选择 Reporting 权限，其他权限按需配置
点击「Confirm」确认后，您的应用最初将处于待定状态。大约一到两天左右，应用可以通过审核（即状态为 Approved）。获取您应用的 App ID 和 Secret
# 二、方案配置
当您在 Tiktok 平台的准备工作后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 Tiktok Basic Report 的配置界面，请您按照本章节内容完成方案的创建
# 2.1 授权信息配置
点击「授权信息」按钮，在弹出框内填写您在上一步中获得的授权信息：
其中 APP ID 与 App Secret 在上一步中获取，Account ID 处填写您需要拉取数据的 Tiktok 广告账号 ID
# 2.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 Tiktok Basic Report 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
# 2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义，字符串类型。 |
| source | report_types | 数据的聚合维度，列表类型，您只能填入一个元素，即一次只拉取一个聚合维度，具体可参考下文 |
| time_granularity | 数据的时间聚合粒度，即拉取的数据以天还是小时进行聚合 可选值: day、hour | |
| metrics | 数据中的指标，列表类型 | |
| group_by | 数据中的分组维度，列表类型 |
Basic Report 提供了以下聚合维度，请注意，Basic Report 仅可以选择一个维度，如果需要按国家（地区）分组，则只能使用 country_code 这一个维度：
| 维度类型 | 维度字段 | 描述 | 是否默认 |
|---|---|---|---|
广告维度 | advertiser_id | Advertiser 层级 | |
| campaign_id | CAMPAIGN 层级 | ||
| adgroup_id | ADGROUP 层级 | ||
| ad_id | AD 层级 | 是 | |
国家（地区）维度 | country_code | 按国家（地区）分组 |
Basic Report 支持的字段非常丰富，以下仅展示最为常见的分组维度以及指标字段，如果想要了解完整的字段列表，请参考 TikTok 的指标列表 (opens new window)。
- 分组维度
下表展示的是目前 TE 默认拉取的分组维度，如果需要调整，请将字段名填写到 source.group_by 中：
| 字段 | 中文名 | 说明备注 |
|---|---|---|
| advertiser_id | 广告账号 ID | 必定入库 |
| campaign_name | 推广系列名称 | 仅 CAMPAIGN、ADGROUP、AD 层级支持 |
| campaign_id | 推广系列ID | 仅 ADGROUP、AD 层级支持 |
| adgroup_name | 广告组名称 | 仅 ADGROUP、AD 层级支持 |
| adgroup_id | 广告组ID | 广告组 ID，仅 AD 层级支持 |
| placement_type | 版位 | 仅 ADGROUP、AD 层级支持 |
| aeo_type | AEO 广告类型 | 枚举值为 Auto Bid Multi Bid IAEO，非 AEO 广告组返回 -。仅 ADGROUP 层级支持 |
| ad_name | 广告名称 | 仅 AD 层级支持 |
| ad_text | 广告标题 | 仅 AD 层级支持 |
| tt_app_id | 推广应用 ID | 仅 ADGROUP、AD 层级支持，当推广对象为 App 时有值 |
| tt_app_name | 推广应用名称 | 仅 ADGROUP、AD 层级支持，当推广对象为 App 时有值 |
| mobile_app_id | 应用 ID | 应用在 Google Play 或 Apple App Store 中的ID，仅 ADGROUP、AD 层级支持，当推广对象为 App 时有值 |
| promotion_type | 推广类型 | 可选值为app（应用）, website（网站）和 others（其他)。ADGROUP 和 AD层级支持。同步报表和异步报表都支持本指标。 |
| dpa_target_audience_type | DPA 广告的目标受众类型 | ADGROUP 和 AD 层级支持。同步报表和异步报表都支持本指标。 |
| currency | 货币 | 货币代码, 比如 USD. 请注意要使currency生效，请求中的 ’dimensions‘字段需有adgroup_id/ ad_id/campaign_id/advertiser_id. |
下表展示的是目前 TE 默认拉取的指标字段，如果需要调整，请将字段名填写到 source.metrics 中：
| 字段 | 中文名 | 说明备注 |
|---|---|---|
| spend | 总消耗 | 在所选择的时间内投放广告产生的花费金额。 |
| cash_spend | 现金消耗 | 所选时间范围内投放广告产生的现金消耗。仅 Advertiser 层级支持，不支持 lifetime，不支持分时查询。 注意：指标更新可能有 24-48 小时的延迟 |
| voucher_spend | 赠款消耗 | 所选时间范围内投放广告产生的赠款消耗。仅 Advertiser 层级支持，不支持 lifetime，不支持分时查询。 注意：指标更新可能有 24-48 小时的延迟 |
| cpc | CPC | 广告花费平均到单次点击的成本。 |
| cpm | CPM | 每千次展现您所产生的平均花费。 |
| impressions | 展示数 | 广告展现次数。 |
| clicks | 点击数 | 广告点击次数。 |
| ctr | CTR (%) | 广告展现中产生了点击的次数占比。 |
| reach | 总覆盖人数 | 至少看过一次广告的人数。该指标为预估所得。 |
| cost_per_1000_reached | 覆盖千人成本 | 覆盖每一千人的平均成本。该指标为预估所得。 |
| conversion | 转化数 | 广告达成目标转化的次数，目标转化会根据创建时的投放设置有所不同（计数结果基于展示时间点统计）。 |
| cost_per_conversion | 转化成本 | 广告花费平均到单次转化的成本（计数结果基于展示时间点统计）。 |
| conversion_rate | 转化率 (%) | 广告点击中产生了转化的次数占比（计数结果基于展示时间点统计）。 |
| real_time_conversion | 实时转化 | 广告达成目标转化的次数，目标转化会根据创建时的投放设置有所不同（计数结果基于转化事件发生的时间统计） |
| real_time_cost_per_conversion | 实时单次转化费用 | 广告花费平均到单次转化的成本（计数结果基于转化事件发生的时间统计） |
| real_time_conversion_rate | 实时转化率 (%) | 广告点击中产生了转化的次数占比（计数结果基于转化事件发生的时间统计） |
| result | 成效 | 广告最终实现成效的次数，与您的优化目标相对应。（计数结果基于展示时间点统计） |
| cost_per_result | 单次成效费用 | 获得单次成效的成本。（计数结果基于展示时间点统计） |
| result_rate | 成效率 (%) | 广告观看或点击过程中获得成效的占比。（计数结果基于展示时间点统计） |
| real_time_result | 实时成效 | 广告最终实现成效的次数，与您的优化目标相对应。（计数结果基于转化事件发生的时间统计） |
| real_time_cost_per_result | 实时单次成效费用 | 获得单次成效的成本。（计数结果基于转化事件发生的时间统计） |
| real_time_result_rate | 实时成效率 (%) | 广告观看或点击过程中获得成效的占比。（计数结果基于转化事件发生的时间统计） |
| secondary_goal_result | 深层目标成效 | 广告最终实现深层目标的次数，与您的深层目标相对应。由于同一推广系列可对应不同的深层目标，当前暂不支持披露推广系列维度的成效数总和，请您前往广告组维度查看对应的深层目标成效数。 |
| cost_per_secondary_goal_result | 深层目标成效费用 | 获得单次深层目标成效的成本。由于同一推广系列可对应不同的深层目标，当前暂不支持披露推广系列维度的深层目标成效费用，请您前往广告组维度查看对应的深层目标成效费用。 |
| secondary_goal_result_rate | 深层目标成效率 (%) | 获得单次深层目标成效的成本。由于同一推广系列可对应不同的深层目标，当前暂不支持披露推广系列维度的深层目标成效费用，请您前往广告组维度查看对应的深层目标成效费用。 |
| frequency | 频次 | 平均每个被覆盖用户的观看次数。 |
| real_time_app_install | 实时应用安装 | 用户在app中激活并归因到您的广告的次数。（计数结果基于转化事件发生的时间统计） |
| real_time_app_install_cost | 实时应用安装成本 | 单次app安装的成本。（计数结果基于转化事件发生的时间统计） |
| app_install | 应用安装 | 用户在app中激活并归因到您的广告的次数。（计数结果基于展示时间点统计。） |
| cost_per_app_install | 应用安装成本 | 单次app安装的成本。（计数结果基于展示时间点统计。） |
| registration | 去重注册数 | 去重后的用户在app中注册并归因到您的广告的次数。（计数结果基于展示时间点统计。） |
| cost_per_registration | 去重注册成本 | 去重后的单次注册的成本。（计数结果基于展示时间点统计。） |
| registration_rate | 注册率 (%) | 去重后的用户的注册量与app激活的占比。（计数结果基于展示时间点统计。） |
# 2.5 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 TE 项目中：
- 由于 Tiktok Marketing API 返回的是聚合数据，因此我们将使用一个固定值作为该数据的用户标识，您可以认为所有数据挂载在一个虚拟用户上
- 我们将使用数据中的 stat_time_day 或 stat_time_hour 字段，作为聚合数据的 #event_time
- 默认的事件名为 -- tiktok_marketing_api_data
# 2.6 标准化字段
如果数据中存在以下事件属性，我们会自动进行标准化处理：
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| advertiser_id | te_ads_object.ad_account_id | 广告账号 ID |
| campaign_name | te_ads_object.campaign_name | 广告计划名 |
| campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| adgroup_name | te_ads_object.ad_group_name | 广告组名 |
| adgroup_id | te_ads_object.ad_group_id | 广告组 ID |
| ad_name | te_ads_object.ad_name | 广告名 |
| ad_id | te_ads_object.ad_id | 广告 ID |
| placement_type | te_ads_object.placement | 广告位置 |
| mobile_app_id | te_ads_object.app_id | 应用 ID |
| tt_app_name | te_ads_object.app_name | 应用名 |
| country_code | te_ads_object.country | 国家地区编码 |
| currency | te_ads_object.currency | 成本或收益的币种 |
| impressions | te_ads_object.impressions | 曝光量 |
| clicks | te_ads_object.clicks | 点击量 |
| app_install | te_ads_object.installs | 转化量（安装） |
| spend | te_ads_object.cost | 买量成本 |
# 2.7 完成授权
完成配置后，您可以点击右上角的「保存并授权」将方案配置保存下来。接下来，您需要完成最后的授权工作：
首先，请在弹出的「授权信息」页面中，将第一步中的地址复制下来
再次回到 Tiktok API Business 页面 (opens new window)，编辑之前创建的应用，编辑 Advertiser redirect URLs，贴入刚刚复制的授权地址。
最后，再回到 TE 界面，点击「前往授权」，此时将打开 Tiktok 的授权页面，按照授权页面的指示完成授权
当您完成了授权之后，请在「授权信息」中点击左下角的「我已完成以上两步操作」后点击右下角的「完成授权」结束配置。至此，您完成了 Tiktok Basic Report 的数据集成。
