简介

分析指标可帮助合作伙伴和广告商了解其在 Twitter 上所推广内容的效果。此类指标包括展示量、点击量、视频观看量和支出等信息。此外,合作伙伴和广告商可以获得覆盖受众的各种细分的详细指标。

广告 API 支持两种方式检索详细的广告活动效果指标:同步和异步。若使用同步分析调用,系统将在响应中返回请求的指标。若使用异步分析端点,则在关联“作业”完成处理后,系统将在可下载的结果文件中提供请求的指标。同步端点支持短时间范围,非常适合实时广告活动优化。异步端点支持更大的时间范围。因此,它们旨在取得更多的数据,非常适合生成报告或历史回填。

详情

同步对比异步

同步与异步分析端点之间的差异,见下表归纳:本信息旨在帮助开发者选择使用哪个端点集合。

  同步 异步
速率限制 用户级:250 个请求/15 分钟 账号级:100 个并发*作业
时间范围 7 天 90 天(未细分)
45 天(细分)
细分
响应返回 指标数据 作业的处理状态**
建议的使用案例 实时优化
用户界面请求
定期安排的同步
回填历史数据

* 是指在任何给定时间可处于某个处理状态的最大作业数。
** 一旦作业成功完成处理,便会返回一个 URL 链接。压缩格式 (gzip) 的结果文件可从这里下载。

除此之外,这两种端点提供的功能相同。

使用案例

共有三种主要分析使用案例。

  1. 实时优化:使用绩效指标更新活跃的广告活动
  2. 同步:定期安排的后台同步
  3. 新账号加载:回填历史数据

同步分析端点可用于实时优化,根据过去 5 至 15 分钟的指标变化更新广告活动。两种端点均可用于分析同步。请记住,期望的时间范围和是否要求细分,将决定使用哪个端点。新账号加载只能使用异步分析端点完成。(请不要使用同步分析端点检索大批量数据。)

如果指标通过后端进程实现同步,则异步分析端点可以为面板和其他 UI 元素提供支持。在实施的过程中,你应当避免调用异步分析端点来实现用户界面请求。

请求选项

分析请求的范围限定于广告账号,因此需要在资源路径中提供账号 ID。下面所列的请求选项被指定为查询参数。以下为要求的值类型。

  • 实体:实体类型,以及你希望请求分析的最多 20 个实体 ID
  • 时间范围:开始和结束时间,按照 ISO 8601 表示
    • 注意:必须用整小时数来表示
  • 指标组:一个或多个相关指标集合(各指标组中的指标列表请参见指标与细分
  • 粒度:指定指标应当返回的聚集水平
  • 展示位置:确定广告指标是否提取自 Twitter 上的广告,或其他位置的广告
    • 注意:每次请求只能指定一个展示位置值

使用 start_timeend_time 请求参数指定一个时间范围。这些值必须按照以下方式与指定粒度对齐。

  1. TOTAL:指定任何时间范围(在端点范围内)
  2. DAY:开始时间和结束时间值均必须在账号时区内与午夜保持一致
  3. HOUR:指定任何时间范围(在端点范围内)

结束时间具有排他性。例如,带 start_time=2019-01-01T00:00:00Zend_time=2019-01-02T00:00:00Z 的请求将返回单日的分析指标值(不是两天),因为该时间范围仅覆盖 24 小时。

细分

只能通过我们的异步分析端点获得。细分让合作伙伴和广告商可以检索分列出特定目标值的指标。要请求细分指标,请使用 segmentation_type 请求参数。有关细分选项的更多详细信息,请参见指标与细分

常见问题

为什么广告 API 的数字与 Twitter 广告用户界面显示的数字不一致?

  • 请确保你已请求两个展示位置的数据:ALL_ON_TWITTERPUBLISHER_NETWORK
  • 记住,广告 API 的结束时间具有排他性;但在广告用户界面中,则不具有排他性

 

数字为什么会随我请求数据的时间而变化?

  • 一旦报告指标可用,你就能够进行检索。它们几乎实时可用。这些早期结果是估算值,因此会发生变化。24 小时后完成指标的最终统计,支出数据除外。
  • 支出指标通常在事件发生后 3 天内最终确定。不过,我们会处理自事件发生之日起最多 14 天的计费数据(例如垃圾信息筛选)。

 

对于某特定的时期,我如何确定请求哪个实体 ID?

 

分析响应中的所有值为什么都为 null

  • 很可能未在请求的时间段内投放广告活动
  • 请使用活跃实体端点确定要针对哪个时间段获取哪些实体的分析

 

为什么用户界面显示 0 时,API 会显示 null 值?

  • 用户界面选择将这些值显示为 0,但这些值是等效的

 

我如何请求与粒度展示位置有关的指标,例如 Twitter 时间线?

  • 在分析中,我们仅支持两个展示位置值:ALL_ON_TWITTERPUBLISHER_NETWORK(即 Twitter 受众平台

 

是否可以检索已删除或暂停的实体的指标?

  • 可以。实体的状态不会影响分析指标的可用性。

 

为什么细分值与非细分值不匹配?

  • 由于该信息的派生方式,细分数据不会 100% 匹配非细分数据。

 

能否请求按多种维度细分的数据?

  • 我们不支持多级细分