批量报告网站事件

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

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

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|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|---|---|---|
|pixel_code{必填}|string |Pixel ID，可在 TikTok 广告平台的事件管理工具中获取。详见“[如何获得pixel_code](https://ads.tiktok.com/marketing_api/docs?id=1739584855420929)”小节。|
|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。<p>例子：</p> <ol><li>SessionID_RandomNumber</li><li>ExternalID_RandomNumber</li><li>BrowserID_RandomNumber</li><li>RandomNumber</li><li>OrderID（针对 Purchase 事件）</li></ol>|
#|timestamp |string|事件发生的时间戳。时间戳需采用 ISO 8601 格式。详见 [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。请注意，如果您没有提供时间戳信息，那么将默认使用TikTok收到该事件的时间。|
#|context|object |有关事件的报告背景信息。详细信息请参考下方的“`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> | <code>13.57.97.131</code>|
#|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/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": {
                "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)。|
|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);