跳转到主要内容

​
转化 API 设置

​
先决条件 

​
Ads API 访问 - 新申请

步骤 1：开发者账户
  • 申请开发者账户时，选择并订阅我们的付费方案，可即时通过审核。
  • 注意：作为最佳实践，强烈建议使用贵公司的官方 X 账号创建开发者账户并申请 Ads API 访问权限。若开发者账户绑定的是个人开发者账号，日后如需转移凭据将无法实现。为便于持续管理，建议归属至公司账户，并按需使用多用户登录。否则，至少应对账户进行个性化设置（页眉图片、头像、个人简介和简介 URL），并开启双重身份验证。
步骤 2：Ads API 申请
  • 请准备好正确的 App ID 以用于 Ads API 申请。可在开发者门户的 Projects & Apps 下找到 App ID。示例：16489123
  • 通过联系您的 X 业务代表申请 Ads API 访问权限。

​
Ads API 访问 - 现有 App

  • 如果你已在使用 Ads API 的现有 App，则该 App 及其现有的 access token 都可用于 Conversion API。

​
Access Tokens

  • 拥有 Ads API 应用的用户句柄所对应的用户 Access Tokens 可直接在开发者门户生成并获取。此类令牌称为你的“personal access token”，因为它用于你自己的 X 句柄。有关身份验证和开发者门户的总体信息请参见此处。
  • 对于非 Ads API 应用所有者的其他用户句柄，其用户 Access Tokens 必须通过三方 OAuth 授权流程生成。使用三方 OAuth 生成 Access Token 的方式包括：
  • 与 Conversion API 搭配使用的任何用户令牌必须对应具有 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别的用户，可通过 authenticated_user_access endpoint 进行检查。
  • 注意： 令牌本身（按上述方式创建后）可共享给不具有 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别的用户使用。

​
步骤

​
创建 Conversion API 事件

要使用 Conversion API，您需要在 Ads Manager 中创建新的转化事件，或复用已与 X Pixel 配合使用的现有事件。如果希望在 Pixel 与 Conversion API 事件之间进行去重，则需要使用先前为 Pixel 创建的同一事件。 
选项 1：在 Ads Manager 中使用现有的转化事件
如果你想使用已与 X pixel 搭配的现有事件，可以直接使用，并从该事件中获取 Event ID。若你对同一事件同时使用 pixel 和 Conversion API，请确保在 Pixel 代码片段和 Conversion API 请求中都使用去重键（在 Conversion API 中为 conversion_id），以对 Pixel 与 Conversion API 之间的同一事件进行去重。更多信息请参见 d. Testing Events and Deduplication 部分。 
选项 2：在 Ads Manager 中创建新的转化事件：
在创建事件之前，需先在 Events Manager 中创建一个 Event Source。要验证你的账户是否已添加 Event Source（X Pixel），请前往 Events Manager，查看左侧菜单中是否有 X Pixel。 如果你尚未添加 Event Source，请按照以下步骤创建：
  1. 访问 ads.x.com
  2. 在左上角进入 Tools，点击 Events Manager
  3. 在右上角选择 Add event source 以 Add an event source；如果你在左侧边栏尚未看到 X pixel event source，请先添加
    1. X pixel event source 的 id 即为你的 Pixel ID
现在你已有一个 Event Source 和 Pixel ID。你需要在该 Event Source 内创建一个事件，以便跟踪你希望监测的转化：
  1. 在 X pixel event source 内，选择右侧的 Add events
  2. 选择使用 Conversion API 安装
  3. 你将看到将在 API 中使用的此事件的 Pixel ID 和 Event ID
    1. 该事件的 id 即为你的 Event ID
  4. 点击 Save，即可创建并启用你的转化事件

​
为转化事件准备标识符 

目前至少需要传递一个标识符，例如 Click ID（twclid）、电子邮件地址或电话号码。若使用 IP 地址或用户代理，则必须再提供第二个标识符，以确保正确的转化匹配。 提供更多标识符将提升转化匹配率。
客户匹配字段格式是否需要哈希处理？
X Click ID由 X 生成（了解更多）否
电子邮件地址去除首尾空格需要（SHA256）
电话号码按照 E.164 标准需要（SHA256）
IP 地址去除首尾空格否
用户代理去除首尾空格否

​
1. 准备 X Click ID 标识符 

建议在转化请求中始终包含 Click ID 当用户跳转到目标网站后，如可用，应从 query（查询）字符串参数 twclid 中解析出 Click ID。  基础 JavaScript 代码示例： 
var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // 建议的下一步操作：记录日志，插入本地存储
}
建议如下： 
  1. 当 URL 的 query（查询）参数中存在 twclid 值时，务必进行解析。
  2. 将 data 与相关的表单 fields 或转化事件信息一并存储。
将 Click ID 与转化事件和工作流信息关联，可支持诸如批处理、基于多重网站导航路径分析并创建转化事件的算法，以及批量上传等场景。 Event Source URL 应进行URL 编码，用于表示触发该事件的网页。

​
2. 准备邮箱标识符 

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

​
3. 准备电话号码标识符 

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

​
4. 准备 IP 地址标识符

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

​
5. 准备 User Agent 标识符

User Agent 需要与另一项标识符（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）。建议实现重试机制并启用基本日志记录，以应对可能返回的错误状态码。 有关该 endpoint 的 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 个事件。 请注意，您的服务器端代码可能需要在此次请求调用之外实现相关逻辑，包括：
  1. 对用户行为进行埋点/记录（日志），以便按事件发送准确的转化数据
  2. 实施必要的逻辑，过滤已行使相关隐私选择的用户所产生的转化事件——例如，他们在广告主网站上选择退出跟踪或个人信息出售
  3. 与事件触发器和页面进行集成，以便捕获事件并发送转化

​
事件测试与去重

​
测试事件

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

​
Pixel 与 Conversion API 之间的去重

如果你希望在 Pixel 与 Conversion API 请求之间对转化进行去重，我们提供 conversion_id 作为去重键。去重仅在事件级别进行。换言之，要在 Pixel 与 CAPI 请求之间实现去重，广告主必须在两者的请求中使用同一事件，并使用相同的 conversion_id。去重仅适用于在 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 天。
尽管各客户的目标、情境与策略各不相同，以下做法已在参与转化追踪 Alpha 或 Beta 的客户中验证有效：创意：
  • 优惠：将折扣、促销或免运费等优惠与 Promoted Tweet 搭配，以提升用户采取行动的意愿
  • 抽奖与竞赛：对知名品牌尤为有效，抽奖与竞赛能带动转化
  • Tweet 文案实验：测试全大写与小写（如 FREE vs free、NOW vs now）
  • 截止时间：设置截止时间以促使人们立刻行动（优惠于 12 月 12 日截止！）
  • 添加吸引人的图片：值得测试在 Tweet 素材中加入更具视觉冲击力的图片是否能提升转化；结果可能因客户的产品/服务而异
定向：
  • @handle 定向与兴趣类别定向：让 Tweet 文案与 @handles 与目标受众高度匹配，有助于提升转化
  • 使用小众但高量的关键词：在演唱会相关场景中，使用与艺人/音乐人相关的关键词（例如其姓名）效果显著
  • Tailored audiences：同时使用 TA web 与转化追踪的客户，相比使用其他定向的对照组，获得了更低的 CPA
广告系列的分层越细致，转化报告的可操作性就越强。例如，优化包含 4 个关键词的系列，比优化包含 50 个关键词的系列要容易得多。

​
Conversion API 的故障排查与支持

如需了解调用 API 后返回的错误代码，请参阅下文相关章节。对于其他问题，请随时联系您的 X 平台代表，我们将尽快协助解决。 

​
错误处理与说明

仅当其中包含的所有转换均无错误时，单个请求才会被视为成功。若某个转换出现任何错误，该 endpoint 将返回所有适用错误的列表。

​
X Ads API 错误代码概览

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

​
当出现 500 系列 HTTP 状态码时，这表示服务器端问题，而非你的请求或账户配置所致。请查看 X API 状态页面 或 开发者社区论坛，以确认是否有他人遇到类似问题。

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

  • 400 Bad Request（请求不符合规范）
  • 401 Unauthorized（身份验证问题）
  • 403 Forbidden（与该开发者账户相关的 API 访问权限问题）
  • 404 Not Found（该 endpoint 的 URL 或参数可能不正确）

​
Conversion API 错误码

​
400 错误请求场景

原因类型错误消息
缺少标识符（目前支持已哈希的电子邮件或 X 点击 ID（twclid））400 错误请求必须至少提供一个用户标识符
无效的已哈希电子邮件400 错误请求Hashed_email 不是有效的 SHA-256 hash
event_id 的类型不是单次事件标签（SET）400 错误请求Event_id (<event_id>) 不是单次事件标签（SET）
请求的转化事件数量超出限制（目前每个请求最多 500 个事件）400 错误请求转化数量上限为 500
缺少事件 ID400 错误请求未找到事件 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) is not a single event tag (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_email": "abc"}]}]}' --header 'Content-Type: application/json'

​
错误信息：

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_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 应用归属用户的其他用户 handle，其 User Access Tokens 必须通过三方 OAuth 授权流程生成。使用三方 OAuth 生成 Access Token 的方式包括： 与 Conversion API 搭配使用的任何用户令牌必须对应具备 AD_MANAGER 或 ACCOUNT_ADMIN 访问级别的用户，可通过 authenticated_user_access endpoint 进行检查。

​
403 访问被禁止 

原因类型错误消息
您正在使用的开发者账户没有 X Ads API 访问权限。在此申请访问。403 未授权的客户端发出此请求且 id 为 <> 的客户端 App 无权访问 X Ads API。请确保您的 App 具备 advertiser-api 访问权限。使用 ‘twurl accounts’ 和 ‘twurl set default <username> <key>’ 来切换您正在使用的 App。

​
404 未找到 

原因类型错误信息
请求的 URL 或参数与该 endpoint 不正确404 路由未找到无法找到请求的资源
您无权访问拥有 pixel_id/Universal website tag 的账户404 未找到用户 <user_id> 无权访问账户 <account_id>。输入“sn <user_id>”以获取该用户的 handle。使用“twurl accounts”和“twurl set default \u003Cusername\u003E”更改您正在使用的用户。
该事件 id 不属于与该 pixel 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 参考，请从列表中选择一个 endpoint：

​
网站转化

转化 APImeasurement/conversions/:pixel_id
网站事件标签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 编码值。

Type: string

Example: o8z6j
conversions
必填		API 请求的 POST 请求体中的对象。转化事件列表。最多可提供 500 个转化事件。请参阅下表了解支持的 fields。

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
conversions 对象
名称说明
conversion_time
必填		以 ISO 8601 表示的时间。

Type: string

Example: 2017-10-05T00:00:00Z
event_id
必填		特定事件的 base-36 ID。它与此广告账户中预先配置的事件相匹配。在 Events Manager 中的对应事件里称为 ID。

Type: string

Example: o87ne 或 tw-o8z6j-o87ne（tw-pixel_id-event-id）均可接受
identifiers
必填		用于匹配转化事件的标识符对象列表。受支持的 fields 列于下方表格。至少需要提供一个标识符对象。

如果使用 IP 地址或 user agent，为确保正确的转化匹配，必须同时发送第二个标识符。

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
可选		事件中购买的商品数量。必须为大于零的正数。

Type: integer

Example: 4
price_currency
可选		事件中购买商品所用的货币，采用 ISO-4217 表示。参见 Currency 了解详细信息。

Type: string

Default: USD

Example: JPY
value
可选		事件中购买商品的价格数值，以 price_currency 指定的货币表示。

Type: double

Example: 100.00
conversion_id
可选		用于像素与 Conversion API 转化之间的去重。可作为同一事件标签中 Web Pixel 与 Conversion API 转化的去重标识符。更多信息参见 Conversions Guide 的 Testing Events and Deduplication 部分。

Type: string

Example: 23294827
description
可选		关于转化的任何附加信息的描述。

Type: string

Example: test conversion
contents
可选		与特定产品/内容相关的明细列表，以提供更细粒度的信息。受支持的 fields 见下方表格。

Type: array

Example: 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 对象
NameDescription
twclid
有时必填		从点击跳转 URL 解析得到的 Click ID。如未提供其他标识符，则必填。

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
有时必填		使用 SHA256 生成 hash 的电子邮件地址。进行 hash 前文本必须为小写，并移除首尾空格。如未提供其他标识符，则必填。

Type: string

Example: 对于 test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
有时必填		按 E164 格式并使用 SHA256 生成 hash 的电话号码。进行 hash 前，电话号码必须符合 E164 格式。如未提供其他标识符，则必填。

Type: string

Example: 对于 +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231
ip_address
有时必填		以点分十进制表示，由四个用句点分隔的数字组成。

IP 地址必须与另一个标识符（twclid、电子邮件地址、电话号码或 user agent）一并传递。

Type: string

Example: 8.25.197.25
user_agent
有时必填		此标识符使服务器能够识别发出请求的 user agent 的应用程序、操作系统、供应商和/或版本。

User agent 必须与另一个标识符（twclid、电子邮件地址、电话号码或 IP 地址）一并传递。

Type: string

Example: 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 对象
NameDescription
content_id
optional		SKU 或 GTIN；用于表示内容的标识符。

Type: string

Example: jhp
content_group_id
optional		与一组产品变体关联的 ID。

Type: integer

Example: group 1
content_name
optional		产品或服务名称。

Type: string

Example: radio flyer
content_price
optional		产品或服务价格。

Type: double

Example: 5.00
content_type
optional		已购买产品的类别。

Type: string

Example: clothes
num_items
optional		购买的产品数量。

Type: integer

Example: 1
响应参数
名称描述
conversions_processed成功处理的转化数量

Type: integer

Example: 1
debug_id可用于后续排查的调试 UUID

Type: string

Example: 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 请求的必需参数。指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
count
可选		指定每个独立请求尝试检索的记录数量。

Type: int

Default: 200
Min, Max: 1, 1000
cursor
可选		指定用于获取下一页结果的游标。更多信息参见 Pagination。

Type: string

Example: 8x7v00oow
sort_by
可选		按支持的属性进行升序或降序排序。更多信息参见 Sorting。

Type: string

Example: created_at-asc
web_event_tag_ids
可选		通过指定以逗号分隔的标识符列表，将响应限定为所需的 Web 事件标签。最多可提供 200 个 ID。

Type: string

Example: o3bk1
with_deleted
可选		在请求中包含已删除的结果。

Type: boolean

Default: false
Possible values: true, false
with_total_count
可选		包含 total_count 响应属性。

注意：此参数与 cursor 互斥。

注意：包含 total_count 的请求将具有更低的请求速率限制，目前为每 15 分钟 200 次。

Type: boolean

Default: false
Possible values: 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": "TRACKING",
          "type": "DOWNLOAD",
          "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 请求的必填参数。所指定的账户必须与已通过身份验证的用户关联。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必填		你在此请求中操作的 web event tag 的引用。

Type: string

Example: o3bk1
with_deleted
可选		是否在请求中包含已删除的结果。

Type: boolean

Default: false
Possible values: 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": "TRACKING",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

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

​
资源 URL

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

​
参数

名称描述
account_id
必填		被使用的账户标识符。出现在资源路径中，且通常是除 GET accounts 之外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
click_window
必填		此网页标签的点击回溯窗口期。

注意：仅接受下列可能的取值。

Type: int

Possible values: 1, 7, 14, 30
name
必填		网页标签名称。

Type: string

Example: Sample single conversion event
retargeting_enabled
必填		是否为此网页标签启用再营销。

Type: boolean

Possible values: true, false
type
必填		网页标签类型。

Type: enum

Possible values: 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 值。

注意：仅接受下列可能的取值。

Type: int

Possible values: 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": "网站事件标签",
        "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": "网站事件标签",
          "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

更新当前账户关联的网页事件标签。
资源 URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
参数

名称说明
account_id
必填		所使用账户的标识符。出现在资源路径中，通常是除 GET accounts 以外所有 Advertiser API 请求的必需参数。指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必填		当前账户中的某个 web tag 的标识符。

Type: string

Example: o3bk1
click_window
可选		此 web tag 的点击回溯窗口。

注意：仅接受下列取值。

Type: int

Possible values: 1, 7, 14, 30
name
可选		web tag 的名称。

Type: string

Example: Sample single conversion event
retargeting_enabled
可选		指示是否为此 web tag 启用再营销。

Type: boolean

Possible values: true, false
type
可选		web tag 的类型。

Type: enum

Possible values: 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
可选		此 web tag 的曝光回溯窗口。该值必须始终小于或等于 click_window 的值。

注意：仅接受下列取值。

Type: int

Possible values: 0, 1, 7, 14, 30

​
示例请求

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

​
示例响应

    {
      "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": "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

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

​
资源 URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
参数
名称描述
account_id
必填		目标账户的标识符。该参数出现在资源路径中，通常是所有 Advertiser API 请求的必填参数（GET accounts 除外）。指定的账户必须与已认证用户关联。

Type: string

Example: 18ce54d4x5t
web_event_tag_id
必填		当前账户中某个 web 标签的标识符。

Type: string

Example: 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": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }
⌘I