← 返回目录
📁 API Reference › Events 1.0 › Pixel Events

报告单个网站事件

您可以使用本接口报告单个网站事件。

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

支持的网站事件

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

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

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

|事件{25%} |事件管理平台中的事件类型{25%}|描述{25%}|<code>properties</code>对象中的推荐参数{25%}|
|---|---|---|---|
|ViewContent|浏览内容|访问页面时事件发生|`content_type`, `quantity, description`, `content_id`, `currency`, `value`|
|ClickButton|点击按钮|点击按钮时发生| |
|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 | 预约 | 预约与您的企业交谈或实地来访 ||

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|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|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`对象参数”小节。|

context对象参数

注意
为了提高网站访问者事件与TikTok广告的匹配成功率，我们建议您尽可能传入更详细的信息。若没有PII信息，我们推荐您同时传入ip以及user_agent。

|字段{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 | | |
#|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>必须在客户端用SHA256加密。 |string|需要在加密前统一使用小写字母。|`0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b`
##|phone_number|用户的电话号码。<br>必须在客户端用SHA256加密。 |string|在加密之前，进行以下格式设置：<ul><li>如果国家代码为+86，需要省略国家代码。（示例：13800000000）</li><li>否则，需添加包含'+'的国家代码，且去掉空格以及其他所有号码间字符(空格，'-')。以美国为例：+12133734253。</li><li>参考文档：[https://github.com/google/libphonenumber](https://github.com/google/libphonenumber)。|`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` |

properties对象参数

|参数 {20%}|描述{27%} | 值类型{17%}|对于广告支出回报率 (ROAS) 是否为必填参数{12%}|对于视频购物广告是否为必填参数{12%}|对于价值优化 (VBO) 是否为必填参数{12%}|
|---|---|---|---|---|
|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| | ||

示例

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


(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": {
    "content_type": "product_group",
    "contents": [
      {
        "price": 8,
        "quantity": 2,
        "content_id": "1077218"
      },
      {
        "price": 30,
        "quantity": 1,        
        "content_id": "1197218"
      }
    ],
    "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|错误详情。|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "request_id": "2019091810032301011023224213558",
    "data":{}
}
(/code);
← 获取Pixel列表创建Pixel →

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