事件 API 2.0
重要提示
使用事件 API 接口代表您同意遵守TikTok 商业产品（数据）条款，并且不会与 TikTok 分享敏感数据。提示
推荐使用事件 API 2.0 （/event/track/）报告来自所有来源（包括网站、应用、线下和 CRM（客户关系管理）系统 ）的事件。该 API 提供了统一的 API 架构，帮助您简化集成过程。
为确保流畅的集成体验，以下 6 个事件 API 1.0 接口将于 2024 年下半年废弃：
强烈推荐新用户直接集成事件 API 2.0 接口，现有的 API 1.0 接口用户尽快升级至事件 API 2.0 接口，从而享受最新版本的各种优点。
简介
TikTok for Business 提供了许多工具，让您可以与 TikTok 共享用户在您的网站上执行的操作。通过与 TikTok 共享事件，您可以更好地优化您的推广系列并衡量广告性能。
TikTok 的事件 API 是一种安全的服务器对服务器集成，允许广告商直接将用户在其网站、应用、线下活动或 CRM 系统中执行的操作与 TikTok 共享。
推荐使用事件 API 2.0 （/event/track/）报告来自所有来源（包括网站、应用、线下和 CRM）的事件。该 API 提供了统一的 API 架构，帮助您简化集成过程。
获取访问令牌
要验证事件 API 调用，您需要一个访问令牌。您可以直接在事件管理平台（推荐）或通过开发者应用生成访问令牌。若想了解获取访问令牌的详情，请查看事件 API 2.0 - 获取访问令牌。
参数概览
以下是事件 API 2.0 有效负载架构的概览。若想了解完整参数列表以及每个参数的详细信息，请查看 API 参考 - 事件 2.0。
请注意，不同的事件来源（例如网站、应用、线下和 CRM 系统）具有不同的必填字段、推荐字段和最佳实践。若想了解每个事件来源类型的特殊要求详情，请查看对应的设置指南： - 事件 API：网站事件 - 事件 API：线下事件 - 事件 API：应用事件 - 事件 API：CRM 事件
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| event_source {必填} | string | 目前支持的枚举值为`web`，`app`，`offline`和 `crm`。|
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。|
| data{必填} | object[] | 您要报告的事件的对象数组。 |
#| event{必填} | string | 转化事件名称，支持设置为标准事件或自定义事件。 |
#| event_time{必填} | integer | 事件发生的时间，以 Unix 时间戳表示。 |
#| event_id | string | 用于设置事件去重的唯一 ID。<br><br>若想了解事件去重的详情，请查看[事件 API 2.0 - 事件去重](1771100965992450.html)。 |
#| limited_data_use | boolean | 仅当 `event_source` 为 `web` 或 `app` 时支持本字段。<br><br> 限制数据使用功能的设置。<br><br> 若想要了解有关限制数据使用功能的更多信息，请查看[事件 API 2.0 - 限制数据使用](1771101204435970.html)。 |
#| user | object | <strong>有关客户的信息。</strong><br><br>若想查看`user`对象中包含的字段，请查看"[`user`参数](https://business-api.tiktok.com/portal/docs?id=1771101303285761#item-link-user参数)"小节。 |
#| properties | object | <strong>有关产品和订单信息和其他附加信息。</strong><br><br> 若想查看`properties`对象中包含的字段，请查看"[`properties`参数](https://business-api.tiktok.com/portal/docs?id=1771101303285761#item-link-properties参数)" 小节。 |
#| page {+条件必填} | object | <strong>有关网页的信息。</strong>网站事件需指定本字段。<br><br> 若想查看`page`对象中包含的字段，请查看"[`page`参数](https://business-api.tiktok.com/portal/docs?id=1771101303285761#item-link-page参数)"小节。 |
#| app {+条件必填} | object | <strong>有关应用的信息。</strong>应用事件需指定本字段。<br><br> 若想查看`app`对象中包含的字段，请查看"[`app`参数](https://business-api.tiktok.com/portal/docs?id=1771101303285761#item-link-app参数)"小节。 <br><br><p><span style="color:darkred"><b>注意</b></span>：使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
#| ad {+条件必填} | object | <strong>有关广告的信息。 </strong>仅应用事件可指定本字段。<br><br>若想查看`ad`对象中包含的字段，请查看"[`ad`参数](https://business-api.tiktok.com/portal/docs?id=1771101303285761#item-link-ad参数)"小节。 |
#| lead {+条件必填} | object | <strong>有关线索的信息。</strong> CRM 事件需指定本字段。<br><br>若想查看`lead`对象中包含的字段，请查看"[`lead`参数](https://ads.tiktok.com/marketing_api/docs?id=1771101303285761#item-link-lead参数)"小节。 |
发送单个事件与发送批量事件
/event/track/ 接口既接受（通过将单个对象传递给data参数的）单个事件，也接受（通过将多个对象传递给data参数的）批量事件。请注意，单个请求中最多可以发送 1,000 个事件。
尽管支持发送批量事件，但强烈建议您在服务器中接收到事件后，每次只发送一个事件。这种事件发生方式可以让 TikTok 充分利用事件来衡量和优化推广系列的效果。
示例：发送单个事件
以下是使用 Curl 的 POST 命令通过事件 API 发送一个最简单的网站事件的示例。
前提条件：您需要有一个 Pixel ID 和一个有效的访问令牌，以替换下文 API 有效负载示例中的 {{Access-Token}}和 {{Pixel-Code}}。若想了解获取访问令牌和 Pxiel ID 的详情，请查看网站事件设置指南。
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/event/track/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"event_source": "web",
"event_source_id": "{{Pixel-Code}}",
"data": [
{
"event": "Purchase",
"event_time": 1684574395
"user": {
"email": "848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f",
"phone": "2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
"ip": "139.177.225.245",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6.1 Safari/605.1.15"
},
"page": {
"url": "http://www.example.com/purchase?q=hello"
}
}
]
}'
(/code)
如果 TikTok 成功接收到事件，API 的返回将带有 HTTP 状态码200和 API 返回码0。以下是 API 调用成功的返回示例：
(code curl http)
HTTP 1.1 200 OK
{
"message": "OK",
"code": 0,
"request_id": "{{request_id}}",
"data":{}
}
(/code)
若请求失败，返回中将带有 HTTP 状态码 4XX 或 5XX ，并在返回的 body 中将有解释了请求失败的原因的 API 错误码和报错信息。若想了解相关详细，请查看事件 API 2.0 - 返回和报错。
API频控
事件 API 2.0 (/event/track/) 对于每个广告主账户（使用事件管理平台生成访问令牌时）或开发者应用（使用自己的开发者应用生成访问令牌时）的频控限制为 1,000 QPS（每秒 1,000 次请求）。若想了解频控限制的详情，请查看频控规则。
若您的业务需要的 QPS 超过了默认的频控限制 1,000 QPS，请联系您的 TikTok 代表。