← 返回目录
📁 Marketing API › Ad Measurement › Guides › Events API 1.0 › Events API : Web

报告网站事件和参数

本文列出了当您使用/pixel/track/或/pixel/batch/报告网站事件时支持的网站事件和参数。

支持的网站事件

事件是指网站访问者为了实现某一业务目标而执行的操作，如将一件商品添加到购物车、填写一个表单或完成一次购买。

TikTok 支持两类事件： - 标准事件：这些事件是带有 TikTok 预定义名称的行为。标准事件目前在所有 TikTok 集成工具中均支持，可用于报告事件、优化转化和创建受众。若想了解支持的标准事件列表，请继续阅读以下内容。 - 自定义事件：这些事件是 TikTok 合作伙伴可以在预定义的标准事件列表外自定义的行为。可以使用事件管理平台中的事件生成器，或直接通过 Pixel 和网站事件 API 报告自定义事件。自定义事件可用于报告事件和受众创建。目前不支持优化。

下表汇总了 18 个标准的网站事件以及每种网站事件在properties对象中的推荐参数。事件名称区分大小写。因此，请务必使用事件列中显示的确切名称。

|事件{25%} |事件管理平台中的事件类型{25%}|描述{25%}|<code>properties</code>对象中的推荐参数{25%}|
|---|---|---|---|
|ViewContent|浏览内容|访问页面时事件发生|`content_type`, `quantity, description`, `content_id`, `currency`, `value`|
|Search|搜索|进行搜索| |
|AddToWishlist|添加到购物清单|某个商品被加入购物清单时||
|AddToCart|添加到购物车|某个商品被加入购物车|`content_type`, `quantity`, `description`, `content_id`,` currency`, `value`|
|ApplicationApproval |批准申请| 批准申请||
|InitiateCheckout|开始下单|开始下单||
|AddPaymentInfo|添加付款信息|支付信息添加到下单流程中||
|Purchase|完成支付|支付完成|`content_type`, `quantity`, `description`, `content_id`, `currency`, `value`|
|Contact|咨询|当联络或咨询发生时| |
|Download|下载|点击按钮打开一个新的浏览器窗口||
|Lead|提交表单|提交了表单||
|CompleteRegistration|完成注册|注册完成时||
|StartTrial|开始试用|开始试用产品或服务.|`currency`, `value`|
|SubmitApplication|提交申请 |提交申请 ||
|Subscribe|订阅|完成订阅||
| CustomizeProduct | 定制商品 | 定制商品 ||
| FindLocation | 寻找位置 | 试图寻找您的位置 ||
| Schedule | 预约 | 预约与您的企业交谈或实地来访 ||

支持的参数

本小节介绍了支持的事件参数、context参数和properties参数。

事件参数

| 字段{30%} |类型{20%}|描述{50%}|
|---|---|---|---|
|pixel_code{必填}|string|Pixel ID，可在 TikTok 广告平台的事件管理平台中找到。详见[常见问题](https://ads.tiktok.com/marketing_api/docs?id=1749819287162881)中的“如何获得pixel_code”。|
|event{必填}|string|转化事件名称。<br><br>支持设置为标准事件或自定义事件。<br><br>支持的标准事件枚举值参见“[支持的网站事件](https://business-api.tiktok.com/portal/docs?id=1740858531237890#item-link-支持的网站事件)”小节。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。|
|event_id|string|用来标示一个独特事件的字符形式或者散列处理后的ID。如果您使用TikTok Pixel 与 Events API 发送了重复的事件，那么您需要填入`event_id`进行去重。详细步骤请查看[事件去重](https://ads.tiktok.com/marketing_api/docs?id=1739584864945154)。<br>示例：<br>1. RandomNumber<br>2. OrderID （针对 Purchase 事件）<br>3. SessionID_RandomNumber<br>4. ExternalID_RandomNumber<br>5. BrowserID_RandomNumber|
|timestamp|string|事件发生的时间戳信息，采用ISO 8601格式。详情可参考[ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。<br>请注意，如果您没有提供时间戳信息，那么将默认使用TikTok收到该事件的时间。|
|context{必填}|object|事件发生的背景环境。您需要传入`context`以进行事件归因。<br>详细信息请参考下方的“`context`对象参数”小节。|
|properties|object|与事件关联的属性。<br>详细信息请参考下方的“`properties`对象参数”小节。|

properties对象参数

下表介绍了properties对象中支持的字段。

|参数 {20%}|描述{27%} | 值类型{17%}|对于广告支出回报率 (ROAS) 或价值优化是否为必填参数{20%}|对于视频购物广告是否为必填参数{16%}|
|---|---|---|---|
|properties|与事件关联的属性，采用 JSON 格式。|object| ||
#|content_type|`content_type`对象属性的值必须设为`product`（商品）或`product_group`（商品组）。<br>如果使用`sku_id`作为`content_id`，则本参数需设置为`product`。  <br>如果使用`item_group_id`作为`content_id`，则本参数需设置为  `product_group`。<br>本参数在视频购物广告场景为必填。 |必须为设置为`product`（商品）或`product_group`（商品组）。| |✅|
#|contents |content对象列表，代表网页事件中对应的有商品信息的商品。|必须为对象数组。| | ✅|
##|price|商品价格。<br><p><span  style="color:darkred"><b>注意</b></span>:  <strong>Price</strong>（价格）是单件商品的价格，而<strong>value</strong>（价值）是指订单的总价。例如，如果您有两件商品，每件商品的销售价格是  10 美元，那么 <code>price</code> 参数需要设置为  <code>10</code>，<code>value</code>参数需要设置为<code>20</code>。  |number| | |
##|quantity|商品数量。|number| | |
##|content_id|商品或内容的唯一ID。  <br>推荐使用 `sku id`  或`item_group_id`。若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。  <br>本参数在视频购物广告场景为必填。|string| |✅ |
##|content_category|页面/商品的类别。|string| | |
##|content_name|页面/商品的名称。|string|| |
##|brand|商品的品牌名称。|string || |
#|currency|ISO 4217  币种代码。示例： `EUR`, `USD`, `JPY`.<br><strong>  目前支持的币种清单：</strong>  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|enum(string)|✅||
#|value|订单或所售商品的价值。  <br><br><p><span  style="color:darkred"><b>注意</b></span>:  <ul><li><strong>Price</strong>（价格）是单件商品的价格，而<strong>value</strong>（价值）是指订单的总价。例如，如果您有两件商品，每件商品的销售价格是  10 美元，那么 <code>price</code> 参数需要设置为  <code>10.00</code>，<code>value</code>参数需要设置为<code>20.00</code>。  </li><li>价值的格式需为整数或小数（例如10.00），不论地域和币种。同时不允许包含币种符号，特殊字符，字母或逗号。</li></ul>|number|✅||
#|query|用户输入的文本字符串。例如，如果有人在您的网站上搜索产品时，您可以发送被搜索的关键词。如果有人在结账时输入优惠券代码，您可以发送该代码。|string| | |
#|description|商品或页面的描述。|string|| |
#|status|订单、商品或服务的状态。<br><p><span style="color:darkred"><b>注意</b></span>:为了能将状态的变化分享给 TikTok，可能需要使用事件 API，具体取决于您对`status`的使用需求。|string| | |

context对象参数

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

我们强烈建议您传入多种类型的匹配数据，以提高受众定位和优化模型的精确度。您可以使用高级匹配、TikTok Click ID 和Cookie进行转化归因。

下表介绍了context对象中支持的字段。

|字段{18%}|描述{30%}|类型{7%}|格式{25%}|示例{20%}|
|---|---|---|---|---|
|context|   Context包含了所有用户信息参数。|object| | 
#|ad| |object| | 
##|callback|TikTok Click ID (`ttclid`)是一个跟踪参数，每当用户点击TikTok上的广告时，该参数就会添加到登陆页面的URL末尾。<br>`ttclid`的有效期限与您在[Attribution Manager](https://ads.tiktok.com/help/article/attribution-manager?redirected=1)中设置的CTA窗口期限相同。<br>详情请见[设置TikTok Click ID和Cookies]((https://ads.tiktok.com/marketing_api/docs?id=1739584860883969)。|string |以“E.C.P.”开头的字符串。 | `"E.C.P.v3fQ2RHacdksKfofPmlyuStIIHJ4Af1tKYxF9zz2c2PLx1Oaw15oHpcfl5AH"`|
#|page|页面信息。 |object| | 
##|url|事件发生时的页面 URL。 |string| | `"http://demo.mywebsite.com/purchase"`
##|referrer| 页面引荐来源。|string| | `"http://demo.mywebsite.com"`
#|user| 用户的个人数据。|object| | 
##|external_id|广告主侧的用户标识符，比如会员ID、用户ID、外部Cookie ID。<br>必须在客户端用SHA256加密。|string| 加密前去除开头和结尾的空格。|`"9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd"`
##|email|用户的邮箱地址。 <br>必须在客户端用SHA-256加密。 |string|<ul><li>需要在散列处理前统一使用小写字母。</li><li>加密前去除开头和结尾的空格并将字母统一处理为小写，在加密前不要对邮箱进行其他预处理。</li><li>仅接受 SHA-256。参考文档：[GitHub - emn178/js-sha256: A simple SHA-256 / SHA-224 hash function for JavaScript supports UTF-8 encoding.](https://github.com/emn178/js-sha256)|`"0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b"`
##|phone_number|用户的电话号码。<br>必须在客户端用SHA-256加密。 |string|<ul><li>将电话号码转为E.164格式，即+［国家/地区代码]［电话号码]。例如，某个美国电话号码的E.164格式：+12133734253</li><li>推荐使用[https://github.com/catamphetamine/libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js)进行E.164解析。</li><li>仅接受 SHA-256。参考文档： [GitHub - emn178/js-sha256: A simple SHA-256 / SHA-224 hash function for JavaScript supports UTF-8 encoding.](https://github.com/emn178/js-sha256)|`"9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd"`
##|ttp|Cookie ID. 如果你使用Pixel SDK并启用了Cookie，Pixel SDK会自动在`_ttp`Cookie中保存一个特殊的标识符。`_ttp`的值用于匹配网站访客事件和TikTok广告。您可以提取`_ttp`的值，并在此处填入该值。<br>获取详细信息，请参考[设置TikTok Click ID和Cookies](https://ads.tiktok.com/marketing_api/docs?id=1739584860883969)。|string| | 
#|ip|浏览器的IP地址。需要为公网IP且不能加密。为了提高网站访问者事件与TikTok广告的匹配成功率，我们推荐同时发送`ip`以及`user_agent`。|string|支持 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|用户设备上的非加密用户代理。<br>为了提高网站访问者事件与TikTok广告的匹配成功率，我们推荐同时发送`ip`以及`user_agent`。|string| |`"Mozilla/5.0 (iPhone; CPU iPhone OS 11_0 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604"`

报告单个网站事件

您可以使用接口/pixel/track/，报告单个网站事件。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ```xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/pixel/track/| /v1.3/pixel/track/


## 请求
**地址**: https://business-api.tiktok.com/open_api/v1.3/pixel/track/


**方法**：POST


**Header**
```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过在 TikTok 广告管理平台导航至 <strong>工具</strong> > <strong>事件</strong> > <strong>网站事件</strong> > 选择任意 Pixel，从而在事件管理平台的“设置”标签页获取。<br>需注意“设置”标签页对所有TikTok 广告管理平台角色可见，但仅广告账户的管理员或操作员可生成访问令牌。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
| --- | --- | --- |
|pixel_code{必填}|string  |Pixel ID，可在 TikTok 广告平台的事件管理平台中找到。详见[常见问题](https://ads.tiktok.com/marketing_api/docs?id=1749819287162881)中的“如何获得pixel_code”。|
|event {必填}|string |转化事件名称。<br><br>支持设置为标准事件或自定义事件。<br><br>支持的标准事件枚举值参见“[支持的网站事件](https://business-api.tiktok.com/portal/docs?id=1740858531237890#item-link-支持的网站事件)”小节。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。|
|event_id  |string |用来标示一个独特事件的字符形式或者散列处理后的ID。如果您使用TikTok Pixel 与 Events API 发送了重复的事件，那么您需要填入`event_id`进行去重。详细步骤请查看[事件去重](https://ads.tiktok.com/marketing_api/docs?id=1739584864945154)。<br>示例：<br>1. RandomNumber<br>2. OrderID  （针对 Purchase 事件）<br>3. SessionID_RandomNumber<br>4. ExternalID_RandomNumber<br>5. BrowserID_RandomNumber |
|timestamp |string  | 事件发生的时间戳信息。详情可参考 [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。请注意，如果您没有提供时间戳信息，那么将默认使用TikTok收到该事件的时间。 |
|context{必填} |object  | 事件发生的背景环境。您需要传入`context`以进行事件归因。可以移除本对象以测试事件。详细信息请参考上方的“`context`对象参数”小节。
|properties |object  |与事件关联的属性。详细信息请参考上方的“`properties`对象参数”小节。|

示例

注意
您需要将示例中的虚拟数据替换为自己的数据。


(code cURL http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/pixel/track/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "pixel_code": "BU35TSQHT2A1QT375GMG",
  "event": "InitiateCheckout",
  "event_id":"1616318632825_357",
  "timestamp": "2020-09-17T19:49:27Z",
  "context": {
    "ad": {
      "callback": "123ATXSfe"
    },
    "page": {
      "url": "http://demo.mywebsite.com/purchase",
      "referrer": "http://demo.mywebsite.com"
    },
    "user": {
      "external_id": "f0e388f53921a51f0bb0fc8a2944109ec188b59172935d8f23020b1614cc44bc",
      "phone_number": "2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
      "email": "dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f",
      "ttp":"94e2a4j9-h3j5-k2h5-98cc-c84a745mk098"
    },
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36",
    "ip": "13.57.97.131"
  },
  "properties": {
    "contents": [
      {
        "price": 8,
        "quantity": 2,
        "content_id": "1077218",
        "content_name": "running shoes",
        "content_category": "Shoes > Sneakers > running shoes",
        "brand": "your_brand_name"
      },
      {
        "price": 30,
        "quantity": 1,
        "content_id": "1197218",
        "content_name": "running shoes",
        "content_category": "Shoes > Sneakers > running shoes",
        "brand": "your_brand_name"
      }
    ],
    "content_type": "product",
    "currency": "USD",
    "value": 46.00
  }
}
'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。若返回码中提示了错误，您需处理对应报错。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。|
|data|object|返回的数据。<br>若调用成功，则返回空对象（`{}`）。|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "request_id": "2019091810032301011023224213558",
    "data":{}
}
(/code);

批量报告网站事件

您可以使用接口/pixel/batch/，批量报告网站事件，减少API的访问量。一个请求最多可报告1000个事件。如果一个请求包含1,000个以上事件，则整个请求会被拒绝。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/pixel/batch/| /v1.3/pixel/batch/| |新增返回参数 |/|partial_failure: boolean <br>failed_events: object[]<br>order_in_batch: number <br>error`: string|


## 请求

**地址** https://business-api.tiktok.com/open_api/v1.3/pixel/batch/

**方法** POST

**Header**

```xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|权访问令牌。可以通过在 TikTok 广告管理平台导航至 <strong>工具</strong> > <strong>事件</strong> > <strong>网站事件</strong> > 选择任意 Pixel，从而在事件管理平台的“设置”标签页获取。<br>需注意“设置”标签页对所有TikTok 广告管理平台角色可见，但仅广告账户的管理员或操作员可生成访问令牌。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|---|---|---|
|pixel_code{必填}|string |可在 TikTok 广告管理平台的事件管理平台中找到的 ID。详见[常见问题](https://ads.tiktok.com/marketing_api/docs?id=1749819287162881)中的“如何获得pixel_code”。|
|batch|object[]|网页事件列表。|
#|type|string|目前仅支持`track`。|
#|event |string|转化事件名称。<br><br>支持设置为标准事件或自定义事件。<br><br>支持的标准事件枚举值参见“[支持的网站事件](https://business-api.tiktok.com/portal/docs?id=1740858531237890#item-link-支持的网站事件)”小节。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。|
#|event_id  |string |用来标示一个独特事件的字符形式或者散列处理后的ID。如果您使用TikTok Pixel 与 Events API 发送了重复的事件，那么您需要填入`event_id`进行去重。详细步骤请查看[事件去重](https://ads.tiktok.com/marketing_api/docs?id=1739584864945154)。<br>示例：<br>1. RandomNumber<br>2. OrderID （针对 Purchase 事件）<br>3. SessionID_RandomNumber<br>4. ExternalID_RandomNumber<br>5. BrowserID_RandomNumber |
#|timestamp |string|事件发生的时间戳。时间戳需采用 ISO 8601 格式。详见 [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。请注意，如果您没有提供时间戳信息，那么将默认使用TikTok收到该事件的时间。|
#|context|object |事件发生的背景环境。您需要传入`context`以进行事件归因。详细信息请参考上方的“`context`对象参数”小节。|
#|properties |object |与事件关联的属性。详细信息请参考上方的“`properties`对象参数”小节。|

示例

注意
您需要将示例中的虚拟数据替换为自己的数据。

(code cURL HTTP)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/pixel/batch/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pixel_code": "PIXEL_CODE",
    "batch": [
        {
            "type": "track",
            "event": "EVENT",
            "event_id": "1616318632825_357",
            "timestamp": "2020-09-17T19:49:27Z",
            "context": {
                "ad": {
                    "callback": "123ATXSfe"
                },
                "page": {
                    "url": "http://demo.mywebsite.com/purchase",
                    "referrer": "http://demo.mywebsite.com"
                },
                "user": {
                    "external_id": "f0e388f53921a51f0bb0fc8a2944109ec188b59172935d8f23020b1614cc44bc",
                    "phone_number": "2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
                    "email": "dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f",
                    "ttp":"94e2a4j9-h3j5-k2h5-98cc-c84a745mk098"
                },
                "user_agent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
                "ip": "13.57.97.131"
            },
            "properties": {
                "contents": [
                   {
                        "price": 8,
                        "quantity": 2,
                        "content_id": "1077218",
                        "content_name": "running shoes",
                        "content_category": "Shoes > Sneakers > running shoes",
                        "brand": "your_brand_name"
                    },
                    {
                        "price": 30,
                        "quantity": 1,
                        "content_id": "1197218",
                        "content_name": "running shoes",
                        "content_category": "Shoes > Sneakers > running shoes",
                        "brand": "your_brand_name"
                    }
                ],
                "content_type": "product",
                "currency": "USD",
                "value": 46.00
            }
        }
    ]
}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data|object|返回数据。|
#|partial_failure   |boolean    |事件报告是否部分失败。|
#|failed_events |object[]|  若发生部分失败，返回错误列表。|
##|order_in_batch| number | 批量请求的顺序。 |
##|error| string | 报错信息。 |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "request_id": "2019091810032301011023224213558",
    "data":{}
}
(/code);
← 设置高级匹配设置 TikTok Click ID 和 Cookie →

内容来源：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 每日平台更新简报 →