← 返回目录
📁 Marketing API › Ad Measurement › Guides › Events API 2.0 › Events API for Web

网站事件设置指南

重要提示
使用事件 API 接口代表您同意遵守TikTok 商业产品（数据）条款，并且不会与 TikTok 分享敏感数据。

快速入门

本指南介绍了使用事件 API 2.0 设置网站事件的流程。

开始前须知

  • 您应具备访问 TikTok 广告管理平台的权限。 TikTok 广告管理平台提供了测试事件功能和诊断工具，助力您的开发测试以及集成后的验证。
  • 您需已在TikTok 广告管理平台 工具 > 事件下创建了 Pixel（网站事件）。
  • 创建 Pixel 完成后，您可以使用代码安装 Pixel 从而通过网站发送事件，或通过事件 API 发送事件。推荐的最佳做法是同时通过网站和事件 API 发送事件，从而最大化您的事件覆盖率和推广系列效果。此外，通过网站 Pixel 和事件 API 的双通道设置，您的推广系列表现将免于事件中断的干扰，因为当其中一个通道失败时，事件信号仍可通过另一通道传递。若您同时从 Pixel SDK 和事件 API 发送事件，则需要设置事件去重。

如果您希望创建一个新的 Pixel，请从第一步开始。
如果您希望使用已有的 Pixel，请直接从第二步开始。

1. 创建 Pixel

a. 在TikTok 广告管理平台中点击工具 > 事件 > 关联数据来源 > 网站。

关联数据来源

b. 添加您的网站

添加您的网站

c. 选择数据连接方式 - 选项 1: 合作伙伴集成 - 选项 2: 手动设置

Alternative Text

  • 若您选择“合作伙伴集成”，请按照屏幕指引选择一个合作伙伴完成设置流程。
  • 若您选择“手动设置”，则有以下设置选项供您选择：
    • TikTok Pixel
    • 事件 API
    • TikTok Pixel + 事件 API

为实现最优表现，推荐同时设置 TikTok Pixel 和事件 API。您需为 Pixel 指定名称并创建 Pixel，随后按照屏幕指引完成设置和 Pixel 创建。

TikTok Pixel + 事件 API

Pixel 创建

2. 生成访问令牌

您需要访问令牌来授权调用事件API。
若想了解如何生成访问令牌，请查看事件 API 2.0 > 获取访问令牌。

此外，还可在 Pixel > 设置中生成访问令牌。

生成访问令牌

通过事件 API 共享事件数据

事件是指网站访问者为了实现某一业务目标而执行的操作，如将一件商品添加到购物车、填写一个表单或完成一次购买。在集成事件 API 之前，我们建议您预先定义要与 TikTok 共享的事件，以实现您的营销目标。您可以在您服务器的有效负载中添加事件和参数，并发送有效负载。

若想了解支持的网站事件和参数，请查看支持的事件 - 网站标准事件。

共享事件的匹配数据

网站事件 API 使用用户信息，例如 TikTok 点击 ID（ttclid）、高级匹配和其他标识（例如 IP 地址和用户代理）匹配网页访客事件与 TikTok 用户。一旦匹配成功，您通过事件 API 共享的信息可用于建立目标受众，为优化算法提供信息，以及更好地衡量广告效果。

验证事件设置

创建事件后，您可以验证网络跟踪设置与监测活动。如果您同时从 Pixel SDK 和事件 API 发送事件，则需要进行事件去重。

若想了解验证事件 API 设置的最佳实践，请查看验证事件 API 设置。

实现最佳效果的最佳实践

为实现事件 API 2.0 的最佳效果，建议进行以下设置： 1. 导航到工具 > 事件 > 数据来源 > 选择一个 Pixel > 设置选项卡，在 TikTok 广告管理平台的 Pixel 设置中，启用第一方 Cookie 和自动高级匹配。请参考下面的截图：

启用第一方 Cookie 和自动高级匹配

  1. 设置 TikTok 点击 ID 和 Cookie。
  2. 发送高级匹配数据。若想了解高级匹配的详情，请查看关于针对网站的高级匹配。作为最佳实践，我们建议您为所有访客事件发送电子邮件地址和电话号码。此外，为获取最佳结果，建议在漏斗的早期阶段就收集访客的电子邮件地址和电话号码。这将增加将客户与 TikTok 上的用户进行匹配的概率。最后，传递电子邮件地址和电话号码的同时，您还可以传递一个外部 ID（例如会员 ID），以获得最佳匹配结果。若想了解外部 ID 的详情，请查看设置外部 ID。
  3. 使用推荐的事件有效负载格式。

地址 https://business-api.tiktok.com/open_api/v1.3/event/track/

方法 POST

Header

|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br><br>若想获取访问令牌，请查看[事件 API 2.0 - 获取访问令牌](1771101130925058.html)。|
|Content-Type {必填}|string|请求信息类型。<br><br>允许格式：`application/json`。|

报告网站事件的参数

每个参数支持的格式参见下表。

注意
若想获取 cURL、Python 和 Node.js 格式的代码示例，从而通过事件 API 2.0 报告网站事件，可使用网站事件的有效负载助手。

顶层参数

|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| event_source {必填} | string | 本字段用于指定通过事件 API 上传的事件类型。<br><br>枚举值：<ul><li>`web`：在您的网站上发生的事件，通过 Pixel 代码追踪。</li></ul> |
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。<br><br> <ul><li>当`event_source`设置为`web`时，需通过本字段指定 Pixel 代码。 <br> 若要获取 Pixel 代码，请查看[常见问题-如何获取Pixel代码](1771101001228290.html)。</li></ul>|
| data{必填} | object[] | 您要报告的事件的对象数组。 <ul><li>若只发送单个事件，请在本对象数组中传递一个对象。</li><li>若要在单个有效负载中批量发送多个事件，则单个请求中的本对象数组最多可包含1,000个对象。</li><li>若单个请求中本对象数组的事件数超过1,000个，整个请求将被拒绝。为了优化广告活动的性能，<strong>强烈建议</strong>您一旦在服务器上捕捉到事件，便<strong>尽快以实时方式（即非批量方式）发送事件</strong>。</li></ul>|
#| event{必填} | string |转化事件名称，支持设置为标准事件或自定义事件。 <br><br>支持的标准事件枚举值参见[事件 API 2.0 - 支持的事件](1771101186666498.html)。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。 |
#| event_time{必填} | integer |事件发生的时间，以 Unix 时间戳表示，以秒为单位，对应时区为 UTC+0 。 |
#| event_id {+条件必填} | string |若您同时从TikTok 浏览器 Pixel 和事件 API发送网站事件（`event_source` = `web`），则本字段必填。 <br><br>用于标识唯一事件的 ID ，允许使用允许使用经散列处理的值或未经散列处理的值。<br><br> TikTok 使用`event_source_id`、`event_id`和`event`对从同一个来源或多个来源（例如浏览器 Pixel 和事件 API）多次发送的相同事件进行去重。 若想了解事件去重及如何完成对应设置的详情，请查看[事件 API 2.0 - 事件去重](1771100965992450.html)。 |
#| user {必填} | object |有关客户的信息。<br><br> 若想查看`user`对象中包含的字段，请查看下文的" <a href="#item-link-ad参数"> `user`参数</a>"小节。 |
#| properties | object |   有关产品和订单信息和其他附加信息，可用于优化广告表现。 <br><br>若想查看`properties`对象中包含的字段，请查看下文的" <a href="#item-link-properties参数"> `properties`参数</a>"小节。 |
#| page {必填} | object |  有关网页的信息。 <br><br>若想查看`page`对象中包含的字段，请查看下文的" <a href="#item-link-page参数">`page`参数 </a>"小节。 |
#| ad |  object |广告相关信息。<br>如需查看 `ad` 对象中包含的字段列表，参见下方的“<a href="#item-link-ad参数">`ad` 参数</a>”小节。|
#| limited_data_use | boolean |  <strong>网站事件、应用事件和线下事件可指定本字段。</strong><br><br> 若想要了解有关限制数据使用功能的更多信息，请查看[事件 API 2.0 - 限制数据使用](1771101204435970.html)。 |

user参数

| 字段{20%} | 类型{15%} | 推荐参数{10%}| 描述{55%} |
|---|---|---|---|
| ttclid | string | ✅| TikTok 点击 ID是一个跟踪参数，每当用户点击 TikTok 上的广告时，该参数就会添加到落地页 URL 的末尾。<br><br>`ttclid`的有效期限与您在[归因管理器](https://ads.tiktok.com/help/article/attribution-manager?redirected=1)中设置的 CTA 窗口期相同。 <br><br>若想了解有关发送 TikTok 点击 ID 的详情，请查看[事件 API 2.0 - 发送TikTok 点击 ID（`ttclid`）](1771100879787009.html)。   |
| email | string 或 string[] |✅|  <strong>需传入经 SHA-256 散列处理的值。</strong><br><br>客户的单个或多个电子邮件地址。  <br><br> 按照以下说明获取有效值：<ul><li>在散列处理之前<strong>去除</strong>每个电子邮件地址<strong>首尾空格</strong>。</li><li>在散列处理之前将所有字符转换为<strong>小写</strong>。</li><li>随后使用 SHA-256 算法对预处理后的电子邮件地址值进行<strong>散列处理</strong>。 </li></ul><br><strong>示例</strong>： <ul><li>原始值：`" ALICE_abc@gmail.com "` </li><li>预处理后的值：`"alice_abc@gmail.com"`（去除首尾空格且字符转换为小写）</li><li> SHA-256 散列处理后的值：`"848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f"` </li></ul>|
| phone | string 或 string[] | ✅| <strong>需传入经 SHA-256 散列处理的值。</strong><br><br>客户的单个或多个电话号码。  <br><br>按照以下说明获取有效值：<ul><li>将电话号码<strong>预处理</strong>为 E.164 格式（例如，"+12133734253"）。建议使用 [https://github.com/catamphetamine/libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js) 进行 E.164 解析。<ul><li>必须包含以 `+` 号为前缀的<strong>国家电话区号</strong>，无任何括号，且开头无`0`。例如，美国电话号码应以国家电话区号`+1`为前缀。</li><li>除了国家代码中的`+`号外<strong>不包括任何空格、字母或符号</strong>。</li></ul> </li><li>在预处理后对电话号码进行<strong> SHA-256 散列处理</strong>。</li></ul><br><br><strong>示例</strong>： <ul><li>原始值："(+1)2133734253"  </li><li>预处理为 E.164 格式："+12133734253"  </li><li> SHA-256 散列处理后的值："9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd" </li></ul> |
| external_id| string 或 string[] | ✅| <strong>需传入经 SHA-256 散列处理的值。</strong><br><br>外部 ID 是广告主侧的唯一标识符，例如会员 ID、用户 ID 和外部 Cookie ID。若想了解 `external_id` 参数的详情，请查看[事件 API 2.0 - 设置外部 ID](1771100952291330.html)。  <br><br>示例：  <ul><li>原始值："user_123"</li><li> SHA-256 散列处理后的值："80fba0ae1c48e3978e43e4efc365e14e12ea0c830ba8ba5b9a2dafc7e3f2ab8b" </li></ul>|
| ttp | string | ✅| Cookie ID。<br><br>若您还使用 Pixel SDK 并启用了 Cookie，Pixel SDK 会在 `_ttp` Cookie 中自动保存一个唯一标识符。`_ttp`的值用于将网站访客事件与 TikTok 广告进行匹配。您可以提取 `_ttp`的值并通过本字段传入。<br><br>若想了解`ttp`参数的详情，请查看[事件 API 2.0 - 发送 TikTok Cookie (`_ttp`)](1771100936446977.html)。 |
| ip | string | ✅|用户设备的未经散列处理的公共 IP 地址。<br><br>为增加网站访客事件与 TikTok 广告的匹配率，建议同时传入 `ip` 和 `user_agent`。<br><br>支持 IPv4 和 IPv6 地址。若为 IPv6 地址，支持传入完整格式或压缩格式。 <br>例如：<ul><li>完整格式：<b>2001:0db8:1111:000a:00b0:0000:0000:0200</b></li><li>压缩格式：<b>2001:db8:1111:a:b0::200</b></li></ul> |
| user_agent | string | ✅|用户设备的未经散列处理的用户代理。<br><br>为增加网站访客事件与 TikTok 广告的匹配率，建议同时传入 `ip` 和 `user_agent`。 |
| locale | string | | BCP 47 语言标识符。<br><br>若想了解该标识符的详情，请查看[IETF BCP 47 标准语言代码](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)。  |

properties参数

| 字段 {20%} | 类型{10%} | 描述{40%} | 对于广告支出回报率 (ROAS) 或<br>价值优化是否为必填参数 {15%}| 对于视频购物广告是否为必填参数 {15%}|
|---|---|---|---|---|
|content_ids| string[]|商品或内容的唯一 ID 或多个 ID 的列表。 <br>示例：`["987","654"]`。 <br>推荐使用 `sku id` 或 `item_group_id`。若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。<br>本参数在视频购物广告场景为必填。 | |✅|
| contents  | object[] | 事件中对应的有商品信息的商品。<br><br>若想查看`contents`对象中包含的字段，请查看下文的"<a href="#item-link-contents参数"> `contents`参数</a>"小节。  | | ✅ |
| content_type  | string | 事件中内容的类型。 <br><br>枚举值：`product`（商品），`product_group`（商品组）。<br><br><ul><li>若`contents`参数中的`content_id`设置为`sku_id`，则本参数需设置为`product`。</li><li>若`contents`参数中的`content_id`设置`item_group_id`，则本参数需设置为 `product_group`。 </li></ul> |  | ✅ |
| currency | string | 推荐为营收相关事件传入本字段。<br><br> ISO 4217 币种代码。<br><br>示例： `EUR`, `USD`, `JPY`。<br><br> 目前支持的币种清单： `AED`，`ARS`，`AUD`，`BDT`，`BHD`，`BIF`，`BOB`，`BRL`，`CAD`，`CHF`，`CLP`，`CNY`，`COP`，`CRC`，`CZK`，`DKK`，`DZD`，`EGP`，`EUR`，`GBP`，`GTQ`，`HKD`，`HNL`，`HUF`，`IDR`，`ILS`，`INR`，`ISK`，`JPY`，`KES`，`KHR`，`KRW`，`KWD`，`KZT`，`MAD`，`MOP`，`MXN`，`MYR`，`NGN`，`NIO`，`NOK`，`NZD`，`OMR`，`PEN`，`PHP`，`PHP`，`PKR`，`PLN`，`PYG`，`QAR`，`RON`，`RUB`，`SAR`，`SEK`，`SGD`，`THB`，`TRY`，`TWD`，`UAH`，`USD`，`VES`，`VND`，`ZAR`| ✅   |   |
| value | float | 推荐为营收相关事件传入本字段。<br><br>订单或所售商品的价值。 <br><br>本字段值的格式需为整数或小数（例如10.00），无论地域、币种或其他因素。同时不允许包含币种符号，特殊字符，字母或逗号。 <br><p><span style="color:darkred"><b>注意</b></span>：`price`（价格）是单件商品的价格，而`value`（价值）是指订单的总价。例如，若您有两件商品，每件商品的销售价格是 10 美元，那么 `price` 参数需要设置为 `10.00`，`value`参数需要设置为`20.00`。 | ✅   | |
|num_items|integer| 商品数量。| | |
|search_string|string|用户输入的用于搜索的文本字符串。| | |
| description | string | 商品或页面的描述。 |  |  |
| order_id | string | 订单 ID。 |  |  |
| shop_id | string | 商店 ID。 |  |  |
|customer_type|string|用于表示与转化事件关联的客户细分群体的类别标签。<br><br>枚举值： <ul><li>`new`：新客户。</li><li>`returning`：老客户。</li></ul>| | |
contents参数
| 字段 {20%} | 类型{10%} | 描述{40%} | 对于广告支出回报率 (ROAS) 或<br>价值优化是否为必填参数 {15%}| 对于视频购物广告是否为必填参数 {15%}|
|---|---|---|---|---|
| price | float | 商品价格。<br><br>示例：`10`，`10.5`。 <br><br><p><span style="color:darkred"><b>注意</b></span>：`price`（价格）是单件商品的价格，而`value`（价值）是指订单的总价。例如，若您有两件商品，每件商品的销售价格是 10 美元，那么 `price` 参数需要设置为 `10.00`，`value`参数需要设置为`20.00`。 | | |
| content_id | string | 商品或内容的唯一ID。 <br><br>推荐使用 `sku_id` 或`item_group_id`。<br><br>若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。| |✅ |
| content_category | string | 页面或商品的类别。 | | |
| content_name | string | 页面或商品的名称。 |  | |
| brand | string | 商品的品牌名称。 | | |

page参数

| 字段{20%} | 类型{10%} | 描述{70%} |
|---|---|---|
| url {必填} | string | 事件发生所在的浏览器 URL，例如客户端 JavaScript 中的 `location.href`的值。 <br>建议使用完整的 URL，包括所有的 URL 参数。 |
| referrer | string | 来源页面的 URL。 例如客户端 JavaScript 中的 [document.referrer](https://developer.mozilla.org/zh-CN/docs/Web/API/Document/referrer)，或服务器端的[Referer 请求头](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Referer)。<br> 建议使用完整的 URL，包括所有的 URL 参数。 |

ad 参数可用于通过事件 API 2.0 分享广告主网站的相关信息。 

| 字段{25%}| 类型{10%}| 描述{65%} |
|---|---|---|
|attribution_share|float| 归因份额分数。<br>你为每次转化打的分数，代表 TikTok 在促成转化方面应获得的贡献比例。分数越高，表明 TikTok 对转化的贡献越大。<br><br>示例：<ul><li>0.0：无贡献。</li><li>0.5：部分贡献。</li><li>1.0：全部贡献。</li></ul>|

有效负载示例

(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": 1687758765,
      "event_id": "12345",
      "user": {
        "external_id": "user_12345678",
        "phone": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
        "email": "123456405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
        "ip": "123.456.789.1",
        "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",
        "locale": "en_US"
      },
      "properties": {
        "currency": "USD",
        "value": 200.0,
        "content_type": "product",
        "description": "some product decription",
        "contents": [
          {
            "price": 100.0,
            "quantity": 2,
            "content_id": "12345",
            "content_name": "Fancy-AirMax2.0 Black",
            "content_category": "Shoes - Running Shoes",
            "brand": "Fancy Sneakers"
          }
        ]
      }
    }
  ]
}'
(/code)
← 发送 TikTok 点击 ID（ttclid）发送 TikTok Cookie（_ttp） →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →