版本

有关 Twitter 广告 API 历史版本的最新信息,请参见下面的信息。

版本

路径

发布日期

弃用日期

生命周期结束日期

版本

路径

/ 10 /    

发布日期

2021 年 8 月 31 日

弃用日期

2022 年 3 月 31 日

生命周期结束日期

版本

9.0

路径

/ 9 /    

发布日期

2021 年 3 月 2 日    

弃用日期

2021 年 8 月 31 日   

生命周期结束日期

2022 年 3 月 31 日

版本

8.0

路径

/ 8 /    

发布日期

2020 年 9 月 8 日    

弃用日期

2021 年 3 月 2 日   

生命周期结束日期

2021 年 8 月 31 日   

版本

7.0

路径

/ 7 /    

发布日期

2020 年 3 月 3 日 

弃用日期

2020 年 9 月 1 日    

生命周期结束日期

2021 年 3 月 2 日    

版本

6.0

路径

/ 6 /    

发布日期

2019 年 8 月 28 日 

弃用日期

2020 年 3 月 3 日 

生命周期结束日期

2020 年 9 月 1 日    

版本

5.0

路径

/ 5 /    

发布日期

2019 年 2 月 28 日 

弃用日期

2019 年 8 月 28 日 

生命周期结束日期

2020 年 3 月 3 日 

版本

4.0

路径

/ 4 /    

发布日期

2018 年 8 月 28 日 

弃用日期

2019 年 2 月 28 日 

生命周期结束日期

2019 年 8 月 28 日 

版本

3.0

路径

/ 3 /    

发布日期

2018 年 2 月 1 日 

弃用日期

2018 年 8 月 28 日 

生命周期结束日期

2019 年 2 月 28 日 

版本

2.0

路径

/ 2 /    

发布日期

2017 年 7 月 10 日 

弃用日期

2018 年 2 月 1 日 

生命周期结束日期

2018 年 8 月 1 日 

版本

1.0

路径

/ 1 /    

发布日期

2016 年 3 月 31 日 

弃用日期

2017 年 7 月 7 日 

生命周期结束日期

2018 年 1 月 10 日 

版本

0.0

路径

/ 0 /    

发布日期

2013 年 2 月 21 日 

弃用日期

不适用 

生命周期结束日期

2016 年 10 月 31 日

概述

每个月,我们都会对 Twitter 广告 API 做出更改并推出几项新功能。虽然这些更改几乎都可向后兼容,但我们往往每年都会做出一些重大变更。开发者已向我们反馈当涉及到实施新功能、处理弃用及测试变更时我们快速变更广告 API 的节奏对他们的开发周期所产生的影响。我们希望使用广告平台提升开发者的体验,因此引入了端点版本控制概念。

我们所讨论的部分概念的定义:

版本:是指任何 Ads API 请求的 URL 路径中存在的版本号,例如:GET /{version_number}/accounts。 这种版本控制称为 URI 版本控制。

重大更改:重大更改是需要开发者资源来维护现有功能的任何更改。这些资源包括用于研究需做出的更改、确定要弃用的功能/端点以及最终实施这些所有更改的资源。重大更改示例如下:

  • 从 API 请求/响应中删除某一参数

  • 修改任何参数或端点的名称

  • 更改值的表示法 (preview_urlcard_uri)

  • 更改端点行为(例如异步与同步统计)

  • 添加/更改可选或必需参数(例如使 name 成为请求中的必需字段)

弃用:我们将不对已弃用版本或产品提供支持,并且建议开发者停止使用这些 API。

废止:产品或 API 废止后,相应的端点组将无法再通过该 API 进行访问。

版本控制策略

版本控制策略的主要原则如下:

  1. 将所有重大更改捆绑到新版本中

  2. 在新版本宣布 6 个月后弃用现有版本

  3. 在任何给定时间,API 允许两个版本同时发出请求,但其中的较旧版本将不受支持

  4. 为实现快速采用新产品,我们将持续不断地(不按版本控制的节奏)发布新产品

  5. 在调用任何已弃用的 API 端点时,所有 API 响应都将包含设置为 API 当前版本的 x-current-api-version,除此之外,还包含 x-api-warn 标头。

如有任何需要重大 API 更改的基本产品要求更改(例如弃用多年龄段定位),我们会提前 90 天发出通知,公告该重大更改,并会在通知发出至少 90 天后部署该重大更改



v9

今天起,即 2021 年 3 月 3 日起,Twitter 广告 API 第 9 版 (v9) 已可用。此版本旨在增强功能奇偶校验、简化广告活动的创建,并为卡片和移动应用推广端点引入关键更新。

对于先前的版本,有 6 个月迁移到 v9 的过渡期。从 2021 年 8 月 31 日开始,现有的广告 API 第 8 版 (v8) 不再可用。我们鼓励所有开发者尽快迁移到最新广告 API 版本,以避免任何服务中断。

注意:从此版本开始,广告 API 第 7 版 (v7) 已达到生命周期末尾,不再可用。

有关详细信息,请参见开发者论坛公告



v8

今天,即 2020 年 9 月 20 日,我们推出了 Twitter 广告 API 第 8 版,旨在引入新的自定义受众功能,增强与 ads.twitter.com 的功能奇偶校验,并改进开发者体验。

对于先前的版本,有 6 个月迁移到 v8 的过渡期。从 2021 年 3 月 2 日开始,广告 API 第 7 版不再可用。我们鼓励所有开发者尽快迁移到最新 API 版本,以避免任何服务中断。

有关详细信息,请参见开发者论坛公告



v7

今天,即 2020 年 3 月 20 日,我们推出了 Twitter 广告 API 第 7 版,旨在提高与 ads.twitter.com 的功能奇偶校验。

对于先前的版本,有 6 个月迁移到 v7 的过渡期。从 2020 年 9 月 1 日开始,广告 API 第 6 版不再可用。我们鼓励所有开发者尽快迁移到最新 API 版本,以避免任何服务中断。广告 API 第 5 版已达到生命周期末尾,不再可用。

有关详细信息,请参见开发者论坛公告



v6

今天(2019 年 8 月 28 日),Twitter 推出了广告 API v6,此次更新重点是提高一致性和改善开发者体验。

此版本提供了一个用于检索推文的新端点、推广账号的统计信息、按名称搜索实体的功能,以及当前正在处理的异步分析作业数量的相关信息。此外,我们还对使用媒体的端点和定位标准端点进行了以一致性为重点的更新。最后,我们对部分参数名称和响应属性进行了小幅更新,并开始停用限定时间线端点。

有关详细信息,请参见开发者论坛公告



v5

Twitter 于 2019 年 2 月 28 日推出广告 API v5,其中的更新侧重于实现规模和效率。

此版本包括一个用于确定在给定时间范围内活动的实体的新端点、媒体素材的统计(即 Twitter 受众平台上的流媒体广告视频和图片)、用于通过卡片 URI 获得多张卡片的功能以及检索定位标准和其他实体的灵活性。此外,我们还修复了一些缺陷并更新了参数名称和响应属性。最后,弃用了非媒体应用卡片和 POST accounts/:account_id/account_media 端点。

对于先前的版本,有 6 个月迁移到 v5 的过渡期。从 2019 年 8 月 28 日 开始,广告 API 第 4 版将不再可用。我们鼓励所有合作伙伴尽快迁移到最新 API 版本,以避免任何服务中断。广告 API 第 3 版已达到生命周期末尾,不再可用。

新功能

确定活动实体

活动实体端点表示广告实体的分析指标是否发生更改。活动实体专门与分析端点一起使用,其通过指定实体类型和日期范围(最长 90 天)来实现,并返回你的平台应该请求分析的实体 ID 数组。不应在后续分析请求中查询已返回 ID 除外的 ID。

此端点支持以下实体类型: CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE 和 PROMOTED_TWEET。

MEDIA_CREATIVE 统计

广告 API 分析端点现在提供媒体素材实体的指标。媒体素材是指流媒体广告或图片在 Twitter 受众平台上的推广方式。在 Twitter 广告用户界面上,媒体素材指标显示在“流媒体广告视频”和“展示素材”选项卡下。同步异步分析端点现在均支持 MEDIA_CREATIVE 实体枚举。

获取多张卡片

对专门通过卡片 URI 值检索单个卡片的端点的 v3 版本进行改进后,现在可使用 GET accounts/:account_id/cards/all 端点获取多张卡片。现在,你可以在一个请求中检索最多 200 个卡片,而不是为每个卡片进行一个请求。

需注意两点:

  1. URL 路径现在为 accounts/:account_id/cards/all。(先前的路径不再可用。) 这是为了与专门用于通过 ID 检索卡片的端点保持一致。
  2. 所需的请求参数现在命名为 card_uris(复数形式)。

检索灵活性

GET accounts/:account_id/targeting_criteria 端点现在支持多个行项目ID。最多可接受 200 个 ID 的 line_item_ids 为必需参数。此前,只能接受一个行项目,因此较难同步。做出此更改后,可以花更少的时间检索更多定位。

以下端点现在还支持多个行项目 ID,但 line_item_ids 参数对于这些端点为可选参数。

更改的内容

检索广告活动草稿和行项目

更新了广告活动草稿和行项目的检索方式。现在,将 with_draft(boolean) 参数设为“true”后,将会同时返回草稿和非草稿实体。这与检索已删除实体(即使用 with_deleted)的方式一致。此前,要同时获取草稿和非草稿实体,至少需要两个请求。现在只需一个 API 调用即可实现。

v4 v5
draft_only with_draft  

网络激活时长定位

添加网络激活时长定位后,响应中的定位类型包含 _IN_SEC 后缀,广告 API 现在已经解决了此显示问题。由于网络激活时长一直以月为单位,引用秒容易令人混淆。此修复实现表示法的一致性并减少了混淆。

v4 v5
NETWORK_ACTIVATION_DURATION_IN_SEC NETWORK_ACTIVATION_DURATION  

总计计数和光标

在 v5 中,with_total_count 和 cursor 相互排斥。如果在请求中同时指定二者,则会返回 EXCLUSIVE_PARAMETERS 错误代码。在 v5 之前的版本中,当请求中指定 cursor 时,会忽略 with_total_count。此更改使这种互斥成为显式关系。

删除的内容

从广告 API 响应中删除了三个字段:preview_url、account_id 和 parent_ids。删除这三个字段需要极少的工程工作。

  • 在 v4 中已公告卡片的 preview_url 响应参数始终为空。此迁移的最后一步是,从所有卡片响应中删除 preview_url。
  • 因为 URL 和请求参数中已存在广告账号 ID,则以下资源将删除 account_id 响应属性。(此列表特意排除了支付手段,因为父级 ID 应该尽可能出现在响应对象中且账号 ID 是支付手段的父实体。)
    • 账号媒体
    • 应用事件提供程序
    • 应用事件标记
    • 广告活动
    • 卡片
    • 行项目
    • 可推广用户
    • 定位标准
  • 对于 GET accounts/:account_id/targeting_criteria 请求,由于 parent_ids 字段一直是空数组,因此我们不再返回此字段。

非媒体应用卡片

v5 将不再支持非媒体应用卡片。 先前,已经删除了创建或编辑非媒体应用卡片的功能。现在,将弃用用于此资源的剩余端点。

  • 注意:这不会影响图片和视频应用下载卡片。

账号媒体创建

v5 不再提供 POST accounts/:account_id/account_media 端点。此资源的其他端点将不受影响。做出此更改的原因是,有时将媒体添加至媒体库时,这些资产会自动添加为账号媒体实体,尝试将已有资产添加到账号媒体资源会导致错误。在以下情况下会发生此问题。

  • 添加至媒体库的 AMPLIFY_VIDEO 资产自动添加为 PREROLL 素材类型的账号媒体资产。
  • 添加至媒体库的特定尺寸的图片自动添加为账号媒体资产。素材类型(例如 INTERSTITIAL)取决于图片尺寸。(关于尺寸,请参见枚举页面。)

 



v4

广告 API 第 4 版于 2018 年 8 月 28 日发布。

此版本包含对我们的受众产品的改进,包括由更稳健的受众处理后端提供支持的全新 API 接口。第 4 版还包含一组用于管理用户、账号和税务设置的端点。此外,将弃用 accounts/:account_id/videos 端点。在此版本中,还对参数和响应名称做了一些次要更改。

对于第 3 版,我们提供 6 个月的过渡期。从 2019 年 2 月 28 日开始,广告 API 第 3 版不再可用。我们鼓励所有合作伙伴尽快迁移到最新 API 版本,以避免任何服务中断。请参见版本页面了解有关版本控制策略的详细信息。

新功能

受众 API

新受众 API 构建于我们全新的受众处理后端之上,该处理后端增强了稳健性和可靠性。此新端点允许合作伙伴为单个用户提供多个用户标识符类型,这意味着我们能够使用额外信号进行匹配。可在此处查看该新受众端点的参考文档。我们计划在今年剩下的时间里继续发布此产品的更新和改进。

由于功能重复,以下端点在 v4 中将不再可用(在 v3 中,这些端点仍然可用,在 v3 不再可用时才完全废止):

  • TON 上传:
    • GET accounts/:account_id/tailored_audience_changes
    • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
    • POST accounts/:account_id/tailored_audience_changes
    • PUT accounts/:accounti_d/tailored_audiences/global_opt_out
  • 实时受众:
    • POST tailored_audience_memberships

最后,第 4 版将从所有自定义受众端点上的请求和响应中移除 list_type 参数。

设置端点

账号管理员现在能够设置及更新用户、账号和税务设置。用户设置对应于给定广告账号的用户特定联系首选项。使用 PUT accounts/:account_id 端点,广告商现在可以更新自己的账号名称和行业类型。最后,税务设置端点允许收取增值税 (VAT) 的国家/地区的广告商更新诸如公司名、地址、增值税 ID 以及账号是广告商还是代表该广告商广告的代理所拥有等信息。

更改的内容

通用相似重命名

我们将更新 POST accounts/:account_id/line_itemsPUT accounts/:accountit/line_items/:line_item_id 端点上 lookalike_expansion 参数的枚举值。

v3 v4
NARROW DEFINED
BALANCED EXPANDED

在任何位置使用 country_code

为了进一步提高广告 API 上的一致性,我们将以下端点上的参数从 app_country_code 重命名为 country_code

此更改不会影响这些参数的行为或接受值,只是命名更改。

preview_url 始终为空

如 v3 通告中所承诺,所有现有卡片现在将都具有 card_uri。因此,preview_url 值将始终为 null

我们在此提醒,请使用卡片的 card_uri 值将卡片与推文关联。请参见下面的示例请求。

$ twurl -X POST -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496"

删除的内容

视频端点

accounts/:account_id/videos 端点在 v4 中将不再可用。引入了媒体库端点,此端点已作废。请参见下面的使用对比。

# v3 videos endpoint
$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/videos"

# v4 media library endpoint for videos
$ twurl -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

媒体库端点完全与视频端点对等,还支持更多功能,例如处理图片和 GIF 的功能。我们要求合作伙伴只将媒体库用于任何媒体管理。

推文视图中的 as_user_id

将不再接受 GET accounts/:account_id/tweet/preview/:tweet_id 端点上提供的 as_user_id 参数。预览将始终呈现为推文的作者。

 



v3

广告 API 第 3 版已于 2018 年 2 月 1 日发布。广告 API 第 2 版的生命周期于 2018 年 8 月 1 日结束。

此版本包括我们新的受众智能产品、媒体库的访问以及卡片工作流程改进。我们还公告弃用 PUT accounts/:account_id/targeting_criteria 端点。最后,第 3 版包含一些次要的参数和响应更改和较低的批处理大小限制。

对于第 2 版,我们给予合作伙伴 6 个月的过渡期。从 2018-08-01 开始,将关闭广告 API v2。我们鼓励所有合作伙伴和开发者尽快迁移到 v3。

受众智能

受众智能提供与给定 Twitter 受众最相关的热门话题标签、@用户名和事件的实时洞察。例如,输入“Male 18-34 in the US”,你便会在此受众中看到“#nintendoswitch”、“#cardinal”和“@ricegumtrending”。

受众智能端点提供以下功能:

  • 根据输入的受众,检索热门相关话题标签、@用户名和事件。
  • 根据输入的受众,检索关键人口统计信息(例如年龄、性别和家庭收入)。
  • 根据关键字,检索推文量时间序列

媒体库

媒体库能够让你管理广告账号的图片、GIF 和视频。这些媒体对象可用于推文中,并可用于创建卡片。它们也可以复用在多个素材中,而无需多次上传相同资产。

媒体库中的对象由 media_key 进行标识。媒体密钥是如下格式的字符串值:13_875943225764098048,示例。在广告 API 中,我们正将媒体密钥用于所有媒体。

卡片工作流程改进

我们所有的卡片端点现在均支持媒体密钥。这使媒体库中的对象可用于创建或更新卡片。

此外,我们推出了两个新端点,用于检索卡片详情。这些端点可用于查找推文或预排期推文中使用的卡片,例如通过指定 card_uriid 来查找。以前,无法进行这种查找。

其他更改

除上述新功能之外,我们还对第 3 版做了以下更改。

新功能

  • GET insights/keywords/search 端点响应现在包含 related_keywords 属性,该属性具有与输入关键字相关的 30 个词语。

更改的内容

  • 现在,最大定位标准批量大小为 500。
  • card_uripreview_url 响应属性现在相互排斥。如果卡片具有 card_uri,则 preview_url 将为空。如果卡片没有 card_uri,则将只返回 preview_url
    • 2018 年 1 月 29 日之后创建的所有卡片都具有 card_uri
    • 在第 4 版中,所有现有卡片都将具有 card_uri
  • 将无法再使用 5:2 图片创建卡片。虽然现有基于 5:2 图片的卡片仍可使用,但我们鼓励合作伙伴改用效果更好的 1.91:1 或 1:1 宽高比图片(如果受支持)

删除的内容

注意

视频网站卡片和预排期推文现在均不再是测试版。请参见此主题帖,了解我们在预排期推文发布后对其做出的更改。这包括为预排期推文生成 HTML 预览的功能。



v2

广告 API 第 2 版于 2017 年 7 月 10 日发布。广告 API 第 1 版的生命周期于 2018 年 1 月 10 日结束。

重大更改/弃用

  • total_count 现在为可选响应属性。只有在将 with_total_count 设置为 true 时,其才可用
  • line_itemscampaigns 请求及响应对象上的 pauseddraft_only 字段被替换为单个 entity_status 参数
  • POST accounts/:account_id/tweetGET accounts/:account_id/tweet/preview 端点上,status 参数已被重命名为 text
  • GET targeting_criteria/locations 端点的 location_type 枚举现在采用复数形式。COUNTRY 现在为 COUNTRIESREGION 现在为 REGIONS,以此类推。但在 v2 中,为了正确反映未知类型引用指定市场区域 (DMA) 或“metros”这一事实,CITY 现在为 METROS
  • PUT accounts/:account_id/promoted_tweets 端点上的 display_properties。响应中也不会再返回这一值
  • 由于上一点,无法再更新 (PUT) promoted_tweets 实体
  • 已将 GET accounts/:account_id/promoted_tweets 端点上的 line_item_id 参数删除
  • 无法再在 v2 端点上创建 5:2 网站卡片
  • 将不会再返回 data_type 响应属性

新功能

  1. 卡片 v2
  2. 广告活动草稿/行项目创建与激活
  3. 预排期推文
  4. 异步作业摘要

卡片 v2

  • 在关联卡片与推文时,应使用 card_uri 请求参数,以将 preview_url 追加到推文文本
  • 如果响应中未返回 card_uri 参数(在卡片创建步骤过程中),则使用 preview_url
  • API 上原生提供所有新卡片格式,从而利用 card_uri 参数。

广告活动草稿

可通过 GET accounts/:account_id/camapaigns 端点查看广告活动草稿。现在可在 v2 中通过 API 创建/激活广告活动草稿。

广告活动草稿 行项目草稿
funding_instrument_id campaign_id
name objective
start_time product_type
  placements
注释
  • 行项目或广告活动草稿只能从 DRAFTentity_status 转换为 PAUSEDACTIVE
  • 若要激活整个广告活动(具有多个行项目),必须将该广告活动下的每个行项目以及该广告活动本身设置为 ACTIVEentity_status
  • 若要更改任何广告活动或行项目的 entity_status,请使用相应的 PUT 端点。



v1

广告 API 第 1 版于 2016 年 3 月 31 日发布并于 2018 年 1 月 10 日达到生命周期末尾。

第 1 版中的更改:

  • 版本控制支持
  • 不再支持 CUSTOM 目标
  • 批量端点现在已正式发布
  • 覆盖预估更改
  • 为更好地预估覆盖,该端点现在感知预算。现在以下参数为必需:
    • [新参数] campaign_daily_budget_amount_local_micro
    • currency
    • bid
    • objective
  • 响应对象已更改,现在会返回响应值的范围。
  • infinite_count 已改名为 infinite_bid_count,以避免混淆其用途
  • countinfinite_bid_count 之外,现在还会返回以下新数据点:
    • impressions
    • engagements
    • estimated_daily_spend_local_micro
  • 自定义受众的数据类型更改
  • 在所有响应中,已将自定义受众的 data_typetailored_audiences 更改为 tailored_audience
  • 共享自定义受众现在作为仅限 API 的测试版提供。共享自定义受众支持跨多个广告账号使用一个受众。使用 POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions(及相关)端点可管理你想跨广告账号共享的自定义受众的权限。
  • 大幅改善为广告商账号收集效果分析的方式:
  • 为了与我们的最佳实践保持一致,我们现在仅允许为同步统计端点拉取最多 7 天的数据。
  • 为简化拉取指标,我们已将 metrics 参数替换为新的 metric_groups 参数。开发者只需请求想为某一给定请求返回的指标组。
    • 对不适合给定实体的指标的任何请求将不包括在响应中并以 null 值表示。这些指标将不会计入你的分析成本限值。
  • 响应已大幅简化,现在将与我们的用户界面中指标的开放方式更加一致。
    • 之前,我们针对每个广告位(搜索中的推广推文、时间线中的推广推文、个人资料和推文详情中的推广推文、Twitter 受众平台)开放了不同的指标。我们现在将针对每个广告位返回一组标准化指标(而非 promoted_tweet_timeline_impressionspromoted_tweet_search_impressionspromoted_tweets_profile_impressionspromoted_tweets_tpn_impressions),当以以下类别之一请求时,这些指标将开放为单个指标,即 impressions(这适用于所有指标):
    • ALL_ON_TWITTER
    • PUBLISHER_NETWORK
    • 当你发出请求时,你会获得一个 impressions 指标,以使我们的用户界面中的匹配值更简单。
    • 你必须进行两次查询,才能获得 ALL_ON_TWITTERPUBLISHER_NETWORK 数据,原因是这些数据无法合并。
  • 根据我们开发人员的反馈,异步统计端点现在可用!
    • 异步请求统计的一组新端点,用于不立即需要的数据或用于历史数据拉取。
    • 使用新的单个端点排队统计作业。我们将按资源的许可拉取你所请求的数据。
    • 你可以查询作业状态端点,以确定数据是否可用。
    • 一旦数据可用,我们会为你提供一个提取 ID,供你下载 JSON 响应,该响应将镜像来自同步端点的响应。
    • 在单个作业中查询最多 20 个实体的最多 90 天数据。
  • 请查看我们的分析 v1 迁移指南,其中包括将 v0 指标映射到 v1 指标的相关指导
  • 沙盒改进 * 你现在可在沙盒环境中创建多个测试广告账号。* 你现在仅可以在沙盒环境中为测试广告账号创建多个支付手段。这允许你测试我们所有的支付手段类型。先前,只有 CREDIT_CARD 支付来源可供测试。* 想要测试一下测试版功能?你现在可以在沙盒环境中打开/关闭账号的功能,以满足你的测试需求。



v0

广告 API 的第 0 版正式发布于 2013 年 2 月 21 日,受支持的时间截止于 2016 年 10 月 31 日。

所有第 0 版分析端点已弃用并在 2016 年 10 月 31 日后不再存在。这些端点已由第 1 版中的 3 个分析端点取代。

覆盖预估端点在第 1 版中具有新作用。