网站转化

设置转化 API

先决条件

Ads API 访问 - 新申请

使用 Conversion API 的主要前提是拥有开发者账户和Ads API 访问权限。流程详见Ads API 入门指南。请注意以下事项：

步骤 1：开发者账户

申请开发者账户时，订阅我们的套餐，即可即时获批。
注意：作为最佳实践，我们强烈建议使用公司官方的 X 账号来创建开发者账户并申请 Ads API 访问权限。如果开发者账户与个人开发者账号关联，所需时无法转移这些凭证。为便于持续管理，最好归属到公司账户，并按需使用多用户登录。否则，至少应将账户从默认状态完善（头图、头像、简介与简介 URL），并启用双重认证。

步骤 2：Ads API 申请

请确保为 Ads API 申请准备好正确的应用ID。可在开发者门户的 Projects & Apps 下找到 App ID。示例：16489123
通过联系你的 X 代表来申请 Ads API 访问权限。

Ads API 访问 - 现有应用

如果你已有一个正在使用的 Ads API 应用，则该应用及其现有访问令牌均可用于 Conversion API。

访问令牌

属于 Ads API 应用所有者的用户句柄，其用户访问令牌可直接在开发者门户中生成并获取。由于它用于你自己的 X 账号，因此称为“个人访问令牌”。有关认证和开发者门户的总体信息请参见此处。
对于非该 Ads API 应用所有者的其他用户句柄，其用户访问令牌必须通过三方（3-legged）OAuth 流程生成。使用三方 OAuth 生成访问令牌的方式包括：
与 Conversion API 搭配使用的任何用户令牌必须对应具有 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别的用户，可通过 authenticated_user_access 端点进行检查。
注意： 令牌本身（按上述方式创建后）可以共享给不具有 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别的用户用于使用。

步骤

创建 Conversion API 事件

要使用 Conversion API，你需要在 Ads Manager 中创建一个新的转化事件，或使用已与 X Pixel 搭配使用的现有事件。如果你希望在 Pixel 与 Conversion API 事件之间进行去重，则需要使用你此前为 Pixel 创建的该现有事件。

选项 1：在 Ads Manager 中使用现有的转化事件

如果你想复用已与 X 像素配合使用的现有事件，可以这么做，你需要从该事件中获取 Event ID。若你对同一事件同时使用像素与 Conversion API，请确保在 Pixel 代码片段和 Conversion API 请求中都使用去重键（作为 conversion_id），以在像素与 Conversion API 之间对该事件进行去重。更多信息请参阅 d. 测试事件与去重。

选项 2：在 Ads Manager 中创建新的转化事件：

在创建事件之前，务必先在 Events Manager 中创建一个事件来源（Event Source）。要确认你的账户是否已添加事件来源（X Pixel），请前往 Events Manager，查看左侧菜单中是否显示 X Pixel。如果你尚未添加事件来源，请按以下步骤创建：

前往 ads.x.com
在左上角进入 Tools，点击 Events Manager
在右上角选择 Add event source 以 Add an event source（如果你在左侧边栏中尚未看到 X pixel event source）
1. X pixel event source 的 ID 即为你的 Pixel ID

现在你已有一个事件来源和 Pixel ID。你需要在该事件来源内创建一个事件，用于跟踪你希望监测的转化：

在 X pixel event source 内，点击右侧的 Add events
选择通过 Conversion API 安装
你将看到此事件的 Pixel ID 和 Event ID，它们将用于 API
1. 事件的 ID 即为你的 Event ID
点击 Save，你的转化事件将被创建并可立即使用

为转化事件准备标识符

目前我们要求至少传递一个标识符，例如 Click ID（twclid）、电子邮件地址或电话号码。若使用 IP 地址或用户代理，则必须同时提供第二个标识符才能实现准确的转化匹配。提供更多标识符将提高转化匹配率。


客户匹配字段	格式	是否需要哈希处理？
X Click ID	由 X 生成（了解更多）	否
电子邮件地址	去除首尾空格	需要（SHA256）
电话号码	E164 标准	需要（SHA256）


IP 地址	去除首尾空格	否
用户代理	去除首尾空格	否

1. 准备 X Click ID 标识符

建议始终在转化请求中包含 Click ID 当用户跳转到目标网站后，如可用，应从查询字符串参数 twclid 中解析出 Click ID。基础 JavaScript 代码示例：

var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // 建议的后续步骤:记录日志,插入到本地存储
}

建议如下：

当 URL 查询参数中包含 twclid 值时，务必对其进行解析。
将该 data 与相关的表单 fields 或转化事件信息一并存储。

将 Click ID 关联到转化事件和工作流信息，可支持诸如批处理、基于多重网站导航路径分析并创建转化事件的算法，以及批量上传等场景。 Event Source URL 应进行URL 编码，用于表示触发该事件的网页。

2. 准备电子邮件标识符

支持的客户匹配字段可以发送，但应先进行规范化，并在需要时进行哈希以保护隐私。信息必须使用 SHA256 进行哈希，且不加盐。例如，对于电子邮件地址 test@x.com，应以哈希值的形式发送给我们：d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62。

3. 准备电话标识符

电话号码应按 E.164 标准传入，且必须使用 SHA-256 在不加盐的情况下进行哈希处理。例如，对于美国电话号码 +11234567890，应将其以哈希后的形式发送给我们：1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231。

4. 准备 IP 地址标识符

IP 地址必须与另一种标识符（twclid、电子邮件地址、电话号码或用户代理）一同传递。此标识符无需进行哈希处理。该值采用点分十进制表示法，由四个用点分隔的数字组成。例如，某位用户的 IP 地址可能是 8.25.197.25。

5. 准备用户代理标识

必须将用户代理与另一个标识（twclid、电子邮件地址、电话号码或 IP 地址）一并传递。此标识无需进行哈希处理。该标识用于让服务器识别发起请求的用户代理所对应的应用、操作系统、供应商及/或版本。例如，该值可以为 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36。

构建转化事件请求

POST: version/measurement/conversions/:pixel_id 向特定广告帐户发送转化事件。应检查响应状态码是否为成功（HTTP 200 OK）。建议在可能返回错误码的情况下，实施重试机制并进行基础日志记录。有关该端点的 URL 和 POST 请求体参数的详细信息，请参见 API 参考部分。

示例请求（为便于阅读进行格式化）

    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"宠物用品购买",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"毯子",
                  "content_type":"宠物用品",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

示例响应

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

速率限制

每个账户在每个 15 分钟窗口内的速率限制为 60,000 个事件。请注意，您的服务器代码可能需要在此请求调用之外实现逻辑，包括：

为按事件发送准确的转化数据，对用户行为进行埋点/日志记录
实现必要的逻辑，以过滤已作出相关隐私选择的用户的转化事件——例如，他们在广告主网站选择退出跟踪或个人信息出售
与事件触发条件和页面进行集成，以便捕获事件并发送转化

测试事件与重复数据消除

测试事件

当你的事件成功接收到转化后，12 至 24 小时内，Ads Manager 的“Conversion Tracking”页面中“Single event web tag”的状态应显示为 TRACKING。通过 Conversion API 发送转化不会影响正在投放的广告系列。你也可以按标签 ID 查看该转化事件的分析结果：

通过 Ads Manager 导出数据（参见网站转化跟踪分析帮助页面）
通过 Ads API 导出数据（segmentation_type=CONVERSION_TAGS）

Pixel 与 Conversion API 之间的去重

如果你希望在 Pixel 与 Conversion API 请求之间对转化进行去重，我们提供 conversion_id 作为去重键。去重仅在事件级别进行。换句话说，要在 Pixel 与 CAPI 请求之间实现去重，广告主除了需要使用相同的 conversion_id 外，还必须在 Pixel 与 CAPI 请求中使用相同的事件。去重仅适用于在 48 小时内接收到的事件。

转化跟踪（概览）

摘要

转化跟踪可帮助你衡量 X 用户在查看并与您在 X 上的广告互动后完成目标行为的人数。它让你能够评估哪些广告系列带动了站点访问、注册和购买等行为。借此，广告主可获得站外测量能力，洞察其直接响应型广告的效果，从而以更具成本效益的方式获客。通过转化标签，广告主可以跟踪用户转化，并将其归因到 X 上的广告系列。这使他们具备优化广告系列以达成每次获客成本（CPA）目标所需的可视性。广告主可通过转化跟踪衡量多种网站行为，并可根据广告系列希望驱动的目标选择一种或多种：

站点访问：用户访问广告主网站的落地页
购买：用户在广告主网站上完成产品或服务的购买
下载：用户从广告主网站下载文件，例如白皮书或软件包
注册：用户注册广告主的服务、订阅新闻简报或接收电子邮件
自定义：用于不属于上述类别的自定义行为的兜底类别

X 的转化跟踪为广告主提供完整的转化归因视图。与客户可能用来替代 X 自身转化跟踪能力的第三方测量系统（例如与第三方跟踪标签配套使用的唯一点击 URL）相比，X 的转化标签可跟踪归因于漏斗中上层互动（例如 Tweet 展开、转发、收藏、回复、关注）以及曝光带来的转化。

常见问题

转化跟踪标签如何运作？

首先，广告主会创建一个转化标签，即由 X 提供的一段代码，并将其部署在自己的网站上。当用户完成指定操作时，该标签即可用于衡量转化。随后，用户会在 X 客户端看到广告主的广告，被引导至广告主网站并执行已被打标签的操作。如果用户在标签设置时广告主指定的归因窗口内完成该操作，标签会识别出该用户此前与 X 广告发生过互动。随后标签将“触发”，即向 X 的服务器发送通知，以便将此次转化归因到带来该转化的广告。

在广告系列设置过程中，是否可以让用户选择与该广告系列相关的跟踪像素？

不可以，我们的产品并不支持将特定转化标签绑定到特定广告系列。相反，一旦完成标签设置，系统会自动记录是哪条广告促成了某个标签上的转化。

转化标签的默认归因窗口设置是什么？

默认曝光后归因窗口：1 天默认互动后归因窗口：14 天这些默认值可在设置转化标签时或标签创建后的任何时间进行更改。互动后归因窗口的可选项为 1、7、14、30、60 和 90 天。曝光后归因窗口的可选项为无、1、7、14、30、60 和 90 天。

有哪些有效的 DR 创意与策略可以促进转化？

虽然每位客户的目标、情境与策略各不相同，但以下做法已在参与转化跟踪内测/公测（alpha/beta）的客户中验证有效：创意：

优惠：将折扣、促销或免邮优惠与推广 Tweet 搭配，以提高用户对目标行动的兴趣
抽奖与竞赛：对知名品牌尤为有效，抽奖与竞赛能带动转化
Tweet 文案测试：测试全大写与小写（FREE vs free 或 NOW vs now）
截止时间：设置截止时间以促使用户立即行动（Offer Expires December 12!）
添加吸引力强的图片：值得测试在 Tweet 创意中加入视觉冲击力强的图片是否能提升转化；结果可能因客户的具体产品/服务而异

定向：

@handle 定向与兴趣类别定向：将 Tweet 文案与 @handles 与目标受众高度匹配，有助于推动转化
使用小众但高搜索量的关键词：在演唱会领域，使用与艺人/音乐人相关的关键词（如其姓名）被证明有效
定制受众：同时使用 TA Web 与转化跟踪的客户，其 CPA 低于使用其他定向方式的对照组

广告系列的分层越精细，你的转化报告就越具可操作性。例如，优化包含 4 个关键词的广告系列要比优化包含 50 个关键词的广告系列容易得多。

转化 API 的故障排查与支持

如果在调用 API 后对错误代码有疑问，请参阅下文章节。对于其他问题，请随时联系您的 X 客户代表，我们将尽快协助解决。

错误处理与说明

只有当请求中包含的所有转化均无任何错误时，单个请求才会被视为成功。若任一转化出现错误，端点将返回该转化所有相关错误的列表。

X Ads API 错误代码概览

以下是 Ads API 中错误代码的完整列表： https://developer.x.com/en/docs/twitter-ads-api/response-codes 成功的 Conversion API 响应会返回 2xx 系列的 HTTP 状态码，并包含一个基于 JSON 的有效负载，其中包含所请求的对象。

出现 400 系列 HTTP 状态码时，常见情况包括

400 Bad Request（请求不符合规范）
401 Unauthorized（认证问题）
403 Forbidden（与该开发者账号关联的 API 访问权限问题）
404 Not Found（该端点的 URL 或参数可能不正确）

Conversion API 错误码

400 错误请求情形

原因	类型	错误消息
缺少标识符（当前为哈希处理的电子邮箱或 X 点击 ID - twclid）	400 错误请求	必须提供至少一个用户标识符
无效的哈希处理电子邮箱	400 错误请求	Hashed_email 不是有效的 SHA-256 哈希值
event_id 的类型不是单次事件标签（SET）	400 错误请求	Event_id (<event_id>) 不是单次事件标签（SET）
请求的转化事件数超出限制（当前每个请求最多 500 个事件）	400 错误请求	转化计数上限为 500
缺少 Event ID	400 错误请求	未找到 Event ID

JSON 错误码示例

请求：

POST '/11/measurement/conversions/o6dkt' --data '{"conversions":[{"conversion_time":"2022-06-16T01:14:00.603Z","event_id":"o6dkt","identifiers":[{"twclid":"23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

错误信息：

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) 不是单个事件标签 (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

请求：

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json'

错误信息：

{"errors":[{"code":"INVALID_PARAMETER","message":"必须至少提供一个用户标识符","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

请求：

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed&#95;email": "abc"}]}]}' --header 'Content-Type: application/json'

错误信息：

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed&#95;email (abc) is not a valid SHA-256 hash","parameter":"hashed&#95;email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

请求：

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

错误信息：

{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

401 未授权

原因：缺少或错误的认证凭据 解决方案：按照设置文档中的认证步骤操作，并使用以下三种认证方式之一：针对非 Ads API 应用所有者的其他用户账号，所使用的用户访问令牌（User Access Tokens）必须通过三方（3-legged）OAuth 流程生成。使用三方 OAuth 生成访问令牌（Access Token）的方式包括：

用于 Conversion API 的任何用户令牌必须属于具有 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别*的用户，并可通过 authenticated_user_access 端点进行验证。

403 访问被拒绝

原因	类型	错误消息
你正在使用的开发者账号没有 Ads API 访问权限。在此申请访问。	403 未授权的客户端	发起此请求、id 为 <> 的客户端应用无法访问 X Ads API。请确保你的应用具有 advertiser-api 访问权限。使用 ‘twurl accounts’ 和 ‘twurl set default <username> <key>’ 更改你正在使用的应用。

404 未找到

原因	类型	错误消息
请求的 URL 或参数不适用于该端点	404 路由未找到	找不到请求的资源
你无权访问拥有 pixel_id/Universal website tag 的账户	404 未找到	用户 <user_id> 无权访问账户 <account_id>。输入“sn <user_id>”以获取该用户的用户名（handle）。使用“twurl accounts”和“twurl set default \u003Cusername\u003E”来更改当前使用的用户。
事件 id 不属于与该像素 ID（UWT ID）关联的提供的账户	404 未找到	event_id <event_id> 不属于提供的账户

JSON 错误码示例

请求：

twurl_ads -X POST '/11/measurement/conversions/o8z6j'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

错误信息：

{"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}

API 参考索引

如需查看完整的 API 参考，请从列表中选择一个端点：

Web 转化


转化 API	measurement/conversions/:pixel_id
Web 事件标签	accounts/:account_id/web_event_tags

POST version/measurement/conversions/:pixel_id 为单个 Event Tag ID 发送网站转化事件。应检查响应状态码以确认成功（HTTP 200 OK）。建议在返回错误码时实施重试机制，并进行基本日志记录。速率限制为每个账户每 15 分钟 100,000 次请求（每个请求最多包含 500 个事件）。

资源URL

https://ads-api.x.com/12/measurement/conversions/:pixel_id

请求 URL 参数

名称	说明
pixel_id 必填	广告账户的 Base Tag ID。表示该广告账户 Base Tag ID 的 base36 编码值。类型：string 示例：`o8z6j`
conversions 必填	API 请求中 POST 正文的对象。转化事件列表，最多可提供 500 个转化事件。有关支持的 fields，请参见下表。类型：array 示例：`"conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]`

conversions 对象

名称	描述
conversion_time 必填	以 ISO 8601 表示的时间。类型：string 示例：`2017-10-05T00:00:00Z`
event_id 必填	特定事件的 base-36 ID。它与此广告账号中预先配置的事件匹配。在 Events Manager 中对应事件里，该字段称为 ID。类型：string 示例：`o87ne` 或 `tw-o8z6j-o87ne`（`tw-pixel_id-event-id`）均可接受
identifiers 必填	用于匹配转化事件的标识符对象列表。支持的字段列于下表。至少需要提供一个标识符对象。如果使用 IP 地址或 user agent，为确保正确的转化匹配，必须同时发送第二个标识符。类型：array 示例：`"identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]`
number_items 可选	事件中购买的商品数量。必须为大于零的正数。类型：integer 示例：`4`
price_currency 可选	事件中购买商品所使用的货币，遵循 ISO-4217 标准。详见 Currency。类型：string 默认值：`USD` 示例：`JPY`
value 可选	事件中所购商品的金额，以 `price_currency` 指定的货币表示。类型：double 示例：`100.00`
conversion_id 可选	用于像素与 Conversion API 转化之间的去重。可作为转化事件的标识符，在_同一事件标签_内对 Web Pixel 与 Conversion API 的转化进行去重。更多信息参见 Conversions Guide 的 Testing Events and Deduplication 部分。类型：string 示例：`23294827`
description 可选	转化的补充说明。类型：string 示例：`test conversion`
contents 可选	与特定产品/内容相关的明细列表，以提供更细粒度的信息。支持的字段见下表。类型：array 示例：`contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]`

identifiers 对象

名称	说明
twclid 有时必填	从点击跳转 URL 解析得到的 Click ID。若未提供任何其他标识符，则必填。类型：string 示例：`26l6412g5p4iyj65a2oic2ayg2`
hashed_email 有时必填	使用 SHA256 哈希的电子邮箱地址。哈希前文本须为小写，并去除首尾空格。若未提供任何其他标识符，则必填。类型：string 示例：`test-email@test.com` 的哈希值为 `e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8`
hashed_phone_number 有时必填	按 E164 格式并使用 SHA256 进行哈希的电话号码。哈希前电话号码必须为 E164 格式。若未提供任何其他标识符，则必填。类型：string 示例：`+11234567890` 的哈希值为 `1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231`
ip_address 有时必填	采用点分十进制表示，由四个用点分隔的数字组成。 IP 地址需与另一个标识符（twclid、电子邮箱地址、电话号码或 user agent）一并传递。类型：string 示例：8.25.197.25
user_agent 有时必填	此标识符用于使服务器识别请求方的应用、操作系统、厂商和/或版本。 User Agent 需与另一个标识符（twclid、电子邮箱地址、电话号码或 IP 地址）一并传递。类型：string 示例：Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

contents 对象

名称	说明
content_id 可选	SKU 或 GTIN；用于标识内容的标识符。类型：string 示例：`jhp`
content_group_id 可选	与一组产品变体关联的 ID。类型：integer 示例：`group 1`
content_name 可选	产品或服务名称。类型：string 示例：`radio flyer`
content_price 可选	产品或服务价格。类型：double 示例：`5.00`
content_type 可选	购买产品的类别。类型：string 示例：`clothes`
num_items 可选	购买的产品数量。类型：integer 示例：`1`

响应参数

名称	说明
conversions_processed	成功处理的转化次数类型：整数示例：`1`
debug_id	可用于后续排查的调试 UUID 类型：字符串示例：`ff02e052-36e4-47d6-bdf0-6d8986446562`

示例请求

    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"宠物用品购买",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"毯子",
                  "content_type":"宠物用品",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

示例请求

    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

Web 事件标签

GET accounts/:account_id/web_event_tags 获取与当前账户关联的全部或部分 Web 事件标签的详细信息。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

参数

名称	说明
account_id 必填	使用的账户标识符。位于资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求所必需的参数。指定的账户必须与已验证的用户关联。类型：string 示例：`18ce54d4x5t`
count 可选	指定每个请求尝试检索的记录数。类型：int 默认值：`200` 最小值、最大值：`1`、`1000`
cursor 可选	指定用于获取下一页结果的游标。更多信息参见分页。类型：string 示例：`8x7v00oow`
sort_by 可选	按支持的属性进行升序或降序排序。更多信息参见排序。类型：string 示例：`created_at-asc`
web_event_tag_ids 可选	通过指定以逗号分隔的标识符列表，将响应限定为所需的 Web 事件标签。最多可提供 200 个 ID。类型：string 示例：`o3bk1`
with_deleted 可选	在请求中包含已删除的结果。类型：boolean 默认值：`false` 可选值：`true`、`false`
with_total_count 可选	在响应中包含 `total_count` 属性。注意：此参数与 `cursor` 互斥。注意：包含 `total_count` 的请求速率限制更低，目前为每 15 分钟 200 次。类型：boolean 默认值：`false` 可选值：`true`、`false`

示例请求

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

示例响应

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "网页事件标签",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "跟踪中",
          "type": "下载",
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/web_event_tags/:web_event_tag_id

获取与当前帐户关联的特定 Web 事件标签。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

参数

名称	描述
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
web_event_tag_id 必填	你在请求中操作的 Web 事件标签的引用。类型：string 示例：`o3bk1`
with_deleted 可选	在请求中包含已删除的结果。类型：boolean 默认值：`false` 可能的取值：`true`、`false`

示例请求

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1

示例响应

    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "网页事件标签",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "跟踪中",
        "type": "下载",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

POST accounts/:account_id/web_event_tags

创建一个与当前账户关联的 Web 事件标签。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

参数

名称	描述
account_id 必填	被使用的账户标识符。出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求必需的参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
click_window 必填	此网页标签的点击回溯窗口期。注意：仅接受以下取值。类型：int 可选取值：`1`、`7`、`14`、`30`
name 必填	网页标签名称。类型：string 示例：`Sample single conversion event`
retargeting_enabled 必填	是否为此网页标签启用再营销（重定向）。类型：boolean 可选取值：`true`、`false`
type 必填	网页标签类型。类型：enum 可选取值：`ADDED_PAYMENT_INFO`、`ADD_TO_CART`、`ADD_TO_WISHLIST`、`CHECKOUT_INITIATED`、`CONTENT_VIEW`、`CUSTOM`、`DOWNLOAD`、`PRODUCT_CUSTOMIZATION`、`PURCHASE`、`SEARCH`、`SIGN_UP`、`SITE_VISIT`、`START_TRIAL`、`SUBSCRIBE` （在 UI 中，`SITE_VISIT` 显示为“Page view”，`SIGN_UP` 显示为“Lead”）
view_through_window 必填	此网页标签的曝光回溯窗口期。该值必须始终小于或等于 `click_window` 的值。注意：仅接受以下取值。类型：int 可选取值：`0`、`1`、`7`、`14`、`30`

示例请求

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

示例响应

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

PUT accounts/:account_id/web_event_tags/:web_event_tag_id

更新与当前账号关联的 Web 事件标签。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

参数

名称	描述
account_id 必填	被使用账户的标识符。出现在资源路径中，通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
web_event_tag_id 必填	当前账户中的某个 Web 标签标识符。类型：string 示例：`o3bk1`
click_window 可选	此 Web 标签的点击回溯窗口。注意：仅接受下方列出的取值。类型：int 可选取值：`1`、`7`、`14`、`30`
name 可选	Web 标签名称。类型：string 示例：`Sample single conversion event`
retargeting_enabled 可选	是否为此 Web 标签启用再营销。类型：boolean 可选取值：`true`、`false`
type 可选	Web 标签类型。类型：enum 可选取值：`ADDED_PAYMENT_INFO`、`ADD_TO_CART`、`ADD_TO_WISHLIST`、`CHECKOUT_INITIATED`、`CONTENT_VIEW`、`CUSTOM`、`DOWNLOAD`、`PRODUCT_CUSTOMIZATION`、`PURCHASE`、`SEARCH`、`SIGN_UP`、`SITE_VISIT`、`START_TRIAL`、`SUBSCRIBE` (在界面中，`SITE_VISIT` 显示为 “Page view”，`SIGN_UP` 显示为 “Lead”)
view_through_window 可选	此 Web 标签的浏览回溯窗口。该值必须小于或等于 `click_window` 的值。注意：仅接受下方列出的取值。类型：int 可选取值：`0`、`1`、`7`、`14`、`30`

示例请求

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

示例响应

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

删除当前账户关联的指定网页事件标签。

资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

参数

名称	描述
account_id 必填	杠杆账户的标识符。该值出现在资源路径中，通常是除 GET accounts 外所有 Advertiser API 请求的必填参数。所指定的账户必须与已认证用户关联。类型：string 示例：`18ce54d4x5t`
web_event_tag_id 必填	当前账户中某个 Web 标签的标识符。类型：string 示例：`o3bk1`

示例请求

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1

示例响应

    {
      "data": {
        "name": "网页事件标签",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "未验证",
        "type": "下载",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }

X 广告 API

基础

资源

测量

​设置转化 API

​先决条件

​Ads API 访问 - 新申请

​Ads API 访问 - 现有应用

​访问令牌

​步骤

​创建 Conversion API 事件

选项 1：在 Ads Manager 中使用现有的转化事件

选项 2：在 Ads Manager 中创建新的转化事件：

​为转化事件准备标识符

​1. 准备 X Click ID 标识符

​2. 准备电子邮件标识符

​3. 准备电话标识符

​4. 准备 IP 地址标识符

​5. 准备用户代理标识

​构建转化事件请求

​示例请求（为便于阅读进行格式化）

​示例响应

​速率限制

​测试事件与重复数据消除

​测试事件

​Pixel 与 Conversion API 之间的去重

​转化跟踪（概览）

​摘要

​常见问题

​转化 API 的故障排查与支持

​错误处理与说明

​X Ads API 错误代码概览

​当出现 5xx 类 HTTP 状态码时，通常是服务器端问题，而非你的请求或账号设置所致。请查看 X API 状态页 或 开发者社区论坛，以确认是否有他人遇到类似问题。

​出现 400 系列 HTTP 状态码时，常见情况包括

​Conversion API 错误码

​400 错误请求情形

​JSON 错误码示例

请求：

​错误信息：

​请求：

​错误信息：

​请求：

​错误信息：

​请求：

​错误信息：

​401 未授权

​403 访问被拒绝

​404 未找到

​JSON 错误码示例

​请求：

​API 参考索引

​Web 转化

​网站转化

资源URL

请求 URL 参数

conversions 对象

identifiers 对象

contents 对象

响应参数

示例请求

示例请求

​Web 事件标签

​资源 URL

​参数

​示例请求

​示例响应

​GET accounts/:account_id/web_event_tags/:web_event_tag_id

资源 URL

参数

示例请求

示例响应

​POST accounts/:account_id/web_event_tags

​资源 URL

​参数

示例请求

​示例响应

​PUT accounts/:account_id/web_event_tags/:web_event_tag_id

资源 URL

​参数

​示例请求

设置转化 API

先决条件

Ads API 访问 - 新申请

Ads API 访问 - 现有应用

访问令牌

步骤

创建 Conversion API 事件

为转化事件准备标识符

1. 准备 X Click ID 标识符

2. 准备电子邮件标识符

3. 准备电话标识符

4. 准备 IP 地址标识符

5. 准备用户代理标识

构建转化事件请求

示例请求（为便于阅读进行格式化）

示例响应

速率限制

测试事件与重复数据消除

测试事件

Pixel 与 Conversion API 之间的去重

转化跟踪（概览）

摘要

常见问题

转化 API 的故障排查与支持

错误处理与说明

X Ads API 错误代码概览

当出现 5xx 类 HTTP 状态码时，通常是服务器端问题，而非你的请求或账号设置所致。请查看 X API 状态页或开发者社区论坛，以确认是否有他人遇到类似问题。

出现 400 系列 HTTP 状态码时，常见情况包括

Conversion API 错误码

400 错误请求情形

JSON 错误码示例

错误信息：

请求：

错误信息：

请求：

错误信息：

请求：

错误信息：

401 未授权

403 访问被拒绝

404 未找到

JSON 错误码示例

请求：

API 参考索引

Web 转化

网站转化

Web 事件标签

资源 URL

参数

示例请求

示例响应

GET accounts/:account_id/web_event_tags/:web_event_tag_id

POST accounts/:account_id/web_event_tags

资源 URL

参数

示例响应

PUT accounts/:account_id/web_event_tags/:web_event_tag_id

参数

示例请求

示例响应

DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

资源 URL