# Twitter Ads 集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Analytic API | API | 聚合指标 | ✅ | ✅ | ✅ | ✅ |
Twitter Ads Analytic API 是 Twitter 提供的聚合数据接口，提供了同步与异步两种数据接口。由于异步数据接口在分析能力以及数据时段上都要优于同步数据接口，因此 TE 系统支持接入异步数据接口 (opens new window)。
# 集成流程
Twitter Ads 数据的接入流程如下：
- 您在 Twitter 平台需要完成：
- 获取 Twitter Developer 账号，创建 APP 并获取 API Key 与 API Token
- 申请 Ads API 的使用权限
- 创建广告账户的 Access Token 与 Access Secret（如果在申请 Ads API 前已创建 Access Token 与 Access Secret，则需要重新生成）
- 登录 TE 后台，进入三方集成模块，新增 Twitter Ads 集成，创建集成方案
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、集成前准备工作
# 1.1 申请 Twitter 开发者账号并创建 APP
如果您想要调用 Twitter API 获取 Twitter Ads 的数据，首先需要申请一个 Twitter 开发者账号 (opens new window)，申请开发者账号需要经过 Twitter 官方的审核。
审核通过后，请创建一个 APP，并记录该 APP 的 API Key 与 API Token，以备后续调用 Ads API 时使用。
# 1.2 申请 Ads API 的使用权限
完成 Twitter 开发者账号的申请后并完成 APP 的创建后，接下来您需要联系 Twitter 工作人员，为您的开发者账号开通 Ads API 的使用权限，申请可能需要花费数日。
# 1.3 获取 Access Token 与 Access Secret
开通 Ads API 的使用权限后，接下来，您需要获取 Access Token 与 Access Secret，回到开发者平台，点击已经申请 Ads API 权限的应用，进入「Keys and tokens」标签页，点击「Access Token and Secret」栏目下的「Generate」按钮，创建 Access Token 与 Access Secret。请务必存放好账户的 Access Token 与 Access Secret，后续调用 Ads API 时需要使用。
# 1.4 总结
您需要在 Twitter 获得以下信息：
- Twitter 应用的 API Key 与 API Key Secret
- 广告账户的 Access Token 与 Access Secret
- 广告账户的 Account ID
# 二、方案配置
当您完成了 Twitter Ads 平台的准备工作后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 Twitter Ads Analytic API 的配置界面，请您按照本章节内容完成方案的创建：
# 2.1 授权信息配置
点击「授权信息」按钮，在弹出框内填写您在 Twiiter Ads 平台中获取到的信息
其中 Account ID List 处请填入需要拉取数据的 Twitter 广告账号 ID，多个广告账号 ID 之间用 "," 号分割
# 2.2 定时拉取
您可以在「定时拉取」模块设置 TE 系统定时拉取 Twitter Ads Analytic API 数据的策略，可以选择在每天的某时或者每小时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据
# 2.3 事件表入库设置
打开「事件表入库设置」开关后，回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的时间聚合粒度，拉取的指标字段与维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义，字符串类型。 |
| source | time_granularity |
数据拉取的时间粒度，可以选择：
|
| metrics | 对应接口的指标字段，列表类型，可以自定义 | |
| transfer | double_columns | 数据中的指标，列表类型，其中的字段会在数据接收时以数值类型入库，其余字段以字符串（或时间）入库 |
Twitter Ads 将 Campaign、Ad Group 等各级广告维度称为「实体 (Entity)」，在调用 Analytic API 时，只允许使用一个分析维度。为了尽可能获取广告维度信息，TE 系统在拉取数据时，将以最细粒度—— PROMOTED_TWEET 作为分析实体，并通过实体关联关系接口获得更高层级实体的信息，比如 Campaign ID、Line Item ID 等。以下表格展示所有维度字段及其含义：
| 维度名 | 含义 |
|---|---|
| account_id | 广告账号 ID |
| campaign_id | Campaign ID |
| campaign_name | Campaign 名 |
| line_item_id | Line Item ID（Ad set ID） |
| line_item_name | Line Item Name（Ad set 名） |
| promoted_tweet_id | Tweet ID |
| placement | 版位 |
| entity_id | 实体 ID |
| currency | 币种 |
Reporting API 提供了多个指标组可供选择，每个指标组涵盖了多个指标字段，您可以自定义需要拉取的指标组，以下表格展示了各指标组的常用指标，如需了解所有指标信息，可以访问 Twitter 官方文档 (opens new window)。如需调整，请将指标组名写入 source.metrics 中，并将指标字段名写入 transfer.double_columns 中
| 指标组 | 指标字段 | 含义 | 是否默认 |
|---|---|---|---|
ENGAGEMENT | engagements | 总曝光数（包含自然曝光、转发、回复、分享、点赞等行为） | 是 |
| impressions | 自然曝光数（不包含付费推广） | 是 | |
| retweets | 转发数 | 是 | |
| replies | 回复数 | 是 | |
| likes | 点赞数 | 是 | |
| follows | 关注数 | 是 | |
| card_engagements | 卡片总曝光数 | 是 | |
| clicks | 点击数 | 是 | |
| app_clicks | 点击后的 APP 安装数或唤起数 | 是 | |
| url_clicks | 点击推文链接或网页卡片的次数 | 是 | |
| qualified_impressions | 完全展示的曝光数 | 是 | |
| carousel_swipes | 轮播图片或视频的滑动次数 | 是 | |
BILLING | billed_engagements | 付费互动数 | 是 |
| billed_charge_local_micro | 付费总金额（扩大 1000000 倍） | 是 | |
VIDEO | video_total_views | 视频播放数 | 是 |
| video_views_25 | 视频 25% 进度播放数 | 是 | |
| video_views_50 | 视频 50% 进度播放数 | 是 | |
| video_views_75 | 视频 75% 进度播放数 | 是 | |
| video_views_100 | 视频完播数 | 是 | |
| video_cta_clicks | Call-to-action 的点击数 | 是 | |
| video_content_starts | 视频录播播放数 | 是 | |
| video_3s100pct_views | 视频完播数（至少观看 3 秒） | 是 | |
| video_6s_views | 视频观看 6 秒播放数 | 是 | |
| video_15s_views | 视频观看 15 秒 或 95% 进度播放数 | 是 | |
MEDIA | media_views | 多媒体观看数 (包含自动播放与点击播放) | 是 |
| media_engagements | 多媒体互动数 | 是 | |
WEB_CONVERSION | conversion_* | 类型为 PURCHASE、SIGN_UP、SITE_VISIT、DOWNLOAD、CUSTOM 的转化事件且后续有付费行为的转化数 | |
MOBILE_CONVERSION | mobile_conversion_* | ||
LIFE_TIME_VALUE_MOBILE_CONVERSION | mobile_conversion_lifetime_value_* |
# 2.5 事件入库规则
- 使用数据中的 day 字段，即数据的日期，设置为聚合数据的 #event_time
- 默认的数据事件名为 -- twitter_ads_data
- 指标字段将以数值类型入库，其他字段以字符串类型入库
# 2.6 标准化字段
Twitter Ads Analytic API 数据中的部分字段，TE 系统会进行标准化处理：
| 字段 | 标准化字段 | 含义 |
|---|---|---|
| account_id | te_ads_object.ad_account_id | 广告账号 ID |
| campaign_id | te_ads_object.campaign_name | 广告计划名 |
| campaign_name | te_ads_object.campaign_id | 广告计划 ID |
| line_item_id | te_ads_object.ad_group_name | 广告组名 |
| line_item_name | te_ads_object.ad_group_id | 广告组 ID |
| promoted_tweet_id | te_ads_object.ad_id | 广告 ID |
| placement | te_ads_object.placement | 广告位置 |
| currency | te_ads_object.currency | 成本或收益的币种 |
| impressions | te_ads_object.impressions | 曝光量 |
| clicks | te_ads_object.clicks | 点击量 |
| billed_charge_local_micro（除以 1000000） | te_ads_object.cost | 买量成本 |