最全Twitter Ads API接入和數據拉回指南

一、集成方案介绍

概要

本文介绍如何通过 Twitter API 将 Twitter Ads 回传数据並存儲在本地，该方案支持：

将 Twitter 消耗、点击、展示等基础报表指标的聚合数据实时 (按小时) 回传到本地數據庫
每天 9 点拉取昨天一整天的数据，并对已有数据进行更新；
按照 Twitter 的广告账号、广告组、广告计划以及推广 Tweet 等维度进行分组；
创建一个“虚拟用户”来承载相关数据并指定 #event_name 和 #event_id。

流程

Twitter Ads 数据的接入流程如下：

您在 Twitter 平台需要完成：
1. 获取 Twitter Developer 账号，创建 APP 并获取 API Key 与 API Token
2. 申请 Ads API 的使用权限
3. 创建广告账户的 Access Token 与 Access Secret（如果在申请 Ads API 前已创建 Access Token 与 Access Secret，则需要重新生成）
您需要獲取以下信息：
1. 具有 Ads API 权限的 APP 的 API Key 与 API Token
2. 广告账户的 Access Token 与 Access Secret
3. 广告账户的 Account ID
确定数据拉取实体类型、数据维度、指标类型、拉取频率以及拉取时间范围
完成数据拉取开发工作
在 TA 后台搭建看板、报表，并完成数据验收

二、集成前准备工作

2.1 申请 Twitter 开发者账号并创建 APP

如果您想要调用 Twitter API 获取 Twitter Ads 的数据，首先需要申请一个 Twitter 开发者账号，申请开发者账号需要经过 Twitter 官方的审核。

审核通过后，请创建一个 APP，并记录该 APP 的 API Key 与 API Token，以备后续调用 Ads API 时使用。

2.2 申请 Ads API 的使用权限

完成 Twitter 开发者账号的申请后并完成 APP 的创建后，接下来请通过以下链接申请 Ads API 的使用权限：Advertising API License Agreement，申请可能需要花费数日。

2.3 获取 Access Token 与 Access Secret

接下来，您需要获取 Access Token 与 Access Secret，回到开发者平台，点击已经申请 Ads API 权限的应用，进入「Keys and tokens」标签页，点击「Access Token and Secret」栏目下的「Generate」按钮，创建 Access Token 与 Access Secret。请务必存放好账户的 Access Token 与 Access Secret，后续调用 Ads API 时需要使用。

2.4 獲取以下信息

API Key 与 API Token
广告账户的 Access Token 与 Access Secret
广告账户的 Account ID

三、数据拉取

接口基本信息

接口名	API 类型	产品化	数据粒度	归因数据	成本数据	收益数据	展示数据	点击数据	转化数据
Report API	拉式	否	聚合数据		是		是	是	是

Report API 是聚合数据接口，Twitter Ads 提供了同步与异步两种数据接口，由于异步数据接口在分析能力以及数据时段上都要优于同步数据接口，因此本方案仅支持接入异步数据接口。

3.1 维度字段

Twitter Ads 将 Campaign、Ad Group 等各级广告维度称为「实体 (Entity)」，在调用 Report API 时，只允许使用一个分析维度。为了尽可能获取广告维度信息，TA 系统在拉取数据时，将以最细粒度—— 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	币种

3.2 涵盖指标

Reporting API 提供了多个指标组可供选择，每个指标组涵盖了多个指标字段，您可以自定义需要拉取的指标组，以下表格展示了各指标组的常用指标，如需了解所有指标信息，可以访问 Twitter 官方文档：

指标组	常用指标	含义
ENGAGEMENT	engagements	总曝光数（包含自然曝光、转发、回复、分享、点赞等行为）
	impressions	自然曝光数（不包含付费推广）
	retweets	转发数
	replies	回复数
	likes	点赞数
	follows	关注数
	card_engagements	卡片总曝光数
	clicks	点击数
	app_clicks	点击后的 APP 安装数或唤起数
	url_clicks	点击推文链接或网页卡片的次数
	qualified_impressions	完全展示的曝光数
	carousel_swipes	轮播图片或视频的滑动次数
BILLING	billed_engagements	付费互动数
BILLING	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	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_*

3.2 接口参数

时间：
- 可以拉取以天为单位、指定时区的数据
版位：
- 将会涵盖 Twitter 和 Twitter Audience Platform 版位的数据

3.3 入库规则

由于 Report API 是聚合数据，因此我们将使用一个固定值作为其用户标识，您可以认为所有数据挂载在一个虚拟用户上
使用数据中的 day 字段，即数据的日期，设置为聚合数据的 #event_time
Report API 的数据事件名为 — twitter_ads_data
指标字段将以数值类型入库，其他字段以字符串类型入库

四、数据集成配置信息模板

在阅读完以上文档之后，请将您的 Twitter 后台app_id, secret, 广告主ID列表信息填写在以下信息框里并发送给您在数数科技的客户成功经理，若您已熟悉对接流程，可以直接填写：

数据接口：Twitter Ads API
---------
数据接收地址 push_url: XXX
---------
Twitter API Key：XXX
Twitter API Token: XXX 
Twitter 账户 Access Token: XXX 
Twitter 账户 Access Token Secret: XXX 
广告主 ID (account_id）列表：XXX
---------
需要拉取的指标组：xxx，xxx
历史数据拉取时间范围：yyyy/mm/dd - yyyy/mm/dd
定时拉取任务：每天 x 点拉取过去 y 天的数据

五、問題解答

在對接任何廣告平台API時，若遇到無論是棘手的技術或者產品問題，歡迎聯繫我幫你解答，查看我的履歷

Tagged Twitter Ads API接入指南