简介
分析指标可帮助合作伙伴和广告商了解其在 Twitter 上所推广内容的效果。此类指标包括展示量、点击量、视频观看量和支出等信息。此外,合作伙伴和广告商可以获得覆盖受众的各种细分的详细指标。
广告 API 支持两种方式检索详细的广告活动效果指标:同步和异步。若使用同步分析调用,系统将在响应中返回请求的指标。若使用异步分析端点,则在关联“作业”完成处理后,系统将在可下载的结果文件中提供请求的指标。同步端点支持短时间范围,非常适合实时广告活动优化。异步端点支持更大的时间范围。因此,它们旨在取得更多的数据,非常适合生成报告或历史回填。
详情
同步对比异步
同步与异步分析端点之间的差异,见下表归纳:本信息旨在帮助开发者选择使用哪个端点集合。
同步 | 异步 | |
速率限制 | 用户级:250 个请求/15 分钟 | 账号级:100 个并发*作业 |
时间范围 | 7 天 | 90 天(未细分) 45 天(细分) |
细分 | 否 | 是 |
响应返回 | 指标数据 | 作业的处理状态** |
建议的使用案例 | 实时优化 用户界面请求 |
定期安排的同步 回填历史数据 |
* 是指在任何给定时间可处于某个处理状态的最大作业数。
** 一旦作业成功完成处理,便会返回一个 URL 链接。压缩格式 (gzip) 的结果文件可从这里下载。
除此之外,这两种端点提供的功能相同。
使用案例
共有三种主要分析使用案例。
- 实时优化:使用绩效指标更新活跃的广告活动
- 同步:定期安排的后台同步
- 新账号加载:回填历史数据
同步分析端点可用于实时优化,根据过去 5 至 15 分钟的指标变化更新广告活动。两种端点均可用于分析同步。请记住,期望的时间范围和是否要求细分,将决定使用哪个端点。新账号加载只能使用异步分析端点完成。(请不要使用同步分析端点检索大批量数据。)
如果指标通过后端进程实现同步,则异步分析端点可以为面板和其他 UI 元素提供支持。在实施的过程中,你应当避免调用异步分析端点来实现用户界面请求。
请求选项
分析请求的范围限定于广告账号,因此需要在资源路径中提供账号 ID。下面所列的请求选项被指定为查询参数。以下为要求的值类型。
- 实体:实体类型,以及你希望请求分析的最多 20 个实体 ID
- 时间范围:开始和结束时间,按照 ISO 8601 表示
- 注意:必须用整小时数来表示
- 指标组:一个或多个相关指标集合(各指标组中的指标列表请参见指标与细分)
- 粒度:指定指标应当返回的聚集水平
- 展示位置:确定广告指标是否提取自 Twitter 上的广告,或其他位置的广告
- 注意:每次请求只能指定一个展示位置值
使用 start_time
和 end_time
请求参数指定一个时间范围。这些值必须按照以下方式与指定粒度对齐。
TOTAL
:指定任何时间范围(在端点范围内)DAY
:开始时间和结束时间值均必须在账号时区内与午夜保持一致HOUR
:指定任何时间范围(在端点范围内)
结束时间具有排他性。例如,带 start_time=2019-01-01T00:00:00Z
和 end_time=2019-01-02T00:00:00Z
的请求将返回单日的分析指标值(不是两天),因为该时间范围仅覆盖 24 小时。
细分
只能通过我们的异步分析端点获得。细分让合作伙伴和广告商可以检索分列出特定目标值的指标。要请求细分指标,请使用 segmentation_type
请求参数。有关细分选项的更多详细信息,请参见指标与细分。
常见问题
为什么广告 API 的数字与 Twitter 广告用户界面显示的数字不一致?
- 请确保你已请求两个展示位置的数据:
ALL_ON_TWITTER
和PUBLISHER_NETWORK
- 记住,广告 API 的结束时间具有排他性;但在广告用户界面中,则不具有排他性
数字为什么会随我请求数据的时间而变化?
- 一旦报告指标可用,你就能够进行检索。它们几乎实时可用。这些早期结果是估算值,因此会发生变化。24 小时后完成指标的最终统计,支出数据除外。
- 支出指标通常在事件发生后 3 天内最终确定。不过,我们会处理自事件发生之日起最多 14 天的计费数据(例如垃圾信息筛选)。
对于某特定的时期,我如何确定请求哪个实体 ID?
- 使用活跃实体端点
分析响应中的所有值为什么都为 null
?
- 很可能未在请求的时间段内投放广告活动
- 请使用活跃实体端点确定要针对哪个时间段获取哪些实体的分析
为什么用户界面显示 0 时,API 会显示 null
值?
- 用户界面选择将这些值显示为 0,但这些值是等效的
我如何请求与粒度展示位置有关的指标,例如 Twitter 时间线?
- 在分析中,我们仅支持两个展示位置值:
ALL_ON_TWITTER
和PUBLISHER_NETWORK
(即 Twitter 受众平台)
是否可以检索已删除或暂停的实体的指标?
- 可以。实体的状态不会影响分析指标的可用性。
为什么细分值与非细分值不匹配?
- 由于该信息的派生方式,细分数据不会 100% 匹配非细分数据。
能否请求按多种维度细分的数据?
- 我们不支持多级细分