← 返回目录
📁 API Reference › Events 2.0

报告应用、网站、线下或 CRM 事件

您可以使用本接口报告单个应用事件、网站事件、线下事件或 CRM （客户关系管理）事件，或批量报告多个应用事件、网站事件、线下事件或 CRM 事件。

请求

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

方法 POST

Header

|字段{20%}|类型{15%}|描述{65%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br><br>若想获取访问令牌，请查看[事件 API 2.0 - 获取访问令牌](https://business-api.tiktok.com/portal/docs/events-api-v2-authentication/v1.3)。|
|Content-Type {必填}|string|请求信息类型。<br><br>允许格式：`application/json`。|

参数

|字段{20%}|类型{15%}|描述{65%}|
|---|---|---|
| event_source {必填} | string | 本字段用于指定通过事件 API 上传的事件类型。<br><br>枚举值：<ul><li>`web`：在您的网站上发生的事件，通过 Pixel 代码追踪。<ul><li>若想获取 cURL、Python 和 Node.js 格式的代码示例，从而通过事件 API 2.0 报告网站事件，可使用[网站事件的有效负载助手](1807346079965186.html)。</li></ul></li><li>`app`：在您的应用程序上发生的事件，通过 TikTok 应用 ID 追踪。</li><li> `offline`：在实体店铺中发生的转化事件，通过线下事件组 ID 追踪。</li><li>`crm`：在 CRM 系统中发生的线索事件，通过 CRM 事件组 ID 追踪。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。<br><br> <ul><li>当`event_source`设置为`web`时，需通过本字段指定 Pixel 代码。 <br> 若要获取 Pixel 代码，请查看[常见问题-如何获取Pixel代码](1771101001228290.html)。</li><li>当`event_source`设置为`offline`时，需通过本字段指定线下事件组 ID。 <br>若要获取线下事件组 ID，请查看[线下事件设置指南](1771101027431425.html)。</li><li>当`event_source`设置为`app`时，需通过本字段指定 TikTok 应用 ID。 <br>若要获取 TikTok 应用 ID，请查看[应用事件设置指南](1771101111730178.html)。</li><li>当`event_source`设置为`crm`时，需通过本字段指定 CRM 事件组 ID。<br>若要获取 CRM 事件组 ID，请使用 [/crm/list/](1780896521680898.html)。</li></ul>|
| data{必填} | object[] | 您要报告的事件的对象数组。 <ul><li>若只发送单个事件，请在本对象数组中传递一个对象。</li><li>若要在单个有效负载中批量发送多个事件，则<strong>单个请求中的本对象数组最多可包含 1,000 个事件</strong>。</li><li>若单个请求中本对象数组的事件数超过 1,000 个，整个请求将被拒绝。为了优化广告活动的性能，<strong>强烈建议</strong>您一旦在服务器上捕捉到事件，便<strong>尽快以实时方式（即非批量方式）发送事件</strong>。</li></ul>|
#| event{必填} | string | <strong>网站事件、应用事件、线下事件和 CRM 事件均需指定本字段。</strong><br><br>转化事件名称。<br><ul><li>若为网站和应用事件，支持设置标准事件或自定义事件。</li><li>若为线下事件，仅支持设置标准事件。</li><li>若为 CRM 事件，仅支持设置自定义事件。</li></ul>支持的标准事件枚举值参见[事件 API 2.0 - 支持的事件](1771101186666498.html)。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。<br>请勿在自定义事件的名称中使用敏感词，以免为可能引发的后果承担相应的责任。 |
#| event_time{必填} | integer | <strong>网站事件、应用事件、线下事件和 CRM 事件均需指定本字段。</strong><br><br>事件发生的时间，以 Unix 时间戳表示，以秒为单位，对应时区为 UTC+0 。 |
#| event_id {+条件必填} | string | <strong>网站事件、线下事件和 CRM 事件均需指定本字段。</strong><br>在以下任意场景中本字段均为必填：<ul><li>同时从 TikTok 浏览器 Pixel 和事件 API 发送网站事件（`event_source` = `web`）时。</li><li>同时通过事件 API 以及在事件管理器上上传 CSV 文件发送 CRM 事件（`event_source` = `crm`）时。 </li></ul><br>用于标识唯一事件的 ID ，允许使用允许使用经散列处理的值或未经散列处理的值。<br><br> TikTok 使用`event_source_id`、`event_id`和`event`对从同一个来源或多个来源（例如浏览器 Pixel 和事件 API）多次发送的相同事件进行去重。 若想了解事件去重及如何完成对应设置的详情，请查看[事件 API 2.0 - 事件去重](1771100965992450.html)。 |
#| user | object |  <strong>网站事件、应用事件、线下事件和 CRM 事件均可指定本字段。 </strong><br><br>有关客户的信息。<br><br> 若想查看`user`对象中包含的字段，请查看下文的" <a href="#item-link-ad参数"> `user`参数</a>"小节。 |
#| properties | object |  <strong>网站事件、应用事件、线下事件和 CRM 事件均可指定本字段。</strong><br><br> 有关产品和订单信息和其他附加信息，可用于优化广告表现。 <br><br>若想查看`properties`对象中包含的字段，请查看下文的" <a href="#item-link-properties参数"> `properties`参数</a>"小节。 |
#| page {+条件必填} | object |  <strong>网站事件需指定本字段。</strong><br><br> 有关网页的信息。 <br><br>若想查看`page`对象中包含的字段，请查看下文的" <a href="#item-link-page参数">`page`参数 </a>"小节。 |
#| app {+条件必填} | object |  <strong>应用事件需指定本字段。</strong><br><br> 有关应用的信息。<br><br>若想查看`app`对象中包含的字段，请查看下文的" <a href="#item-link-app参数"> `app`参数</a>"小节。 <br><br><p><span style="color:darkred"><b>注意</b></span>：使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
#| ad | object |  <strong>应用事件和网站事件可指定本字段。 </strong><br><br>有关广告的信息。<br><br>若想查看`ad`对象中包含的字段，请查看下文的" <a href="#item-link-ad参数">`ad`参数 </a>"小节。 |
#| limited_data_use | boolean |  <strong>网站事件和应用事件可指定本字段。</strong><br><br> 若想要了解有关限制数据使用功能的更多信息，请查看[事件 API 2.0 - 限制数据使用](1771101204435970.html)。 |
#| lead {+条件必填} | object | <strong>CRM 事件需指定本字段。</strong><br><br>有关线索的信息。 <br>对象中包含的字段，请查看下文的"<a href="#item-link-lead参数">`lead`参数</a>"小节。 |

user参数

事件 API 2.0 使用客户信息，例如 TikTok 点击 ID、高级匹配以及其他信号（如 IP 地址和用户代理），将网页访问者事件与 TikTok 用户进行匹配。一旦匹配成功，通过事件 API 分享的信息可用于构建定向受众，为优化算法提供数据，以及优化对推广系列效果的度量。

为了提高定向和优化模型的准确性，强烈建议包括多种类型的匹配数据。您可以使用高级匹配、TikTok 点击 ID（ttclid）和 Cookie 来对转化进行归因。

| 字段{15%} | 类型{15%} | 描述{40%} | 示例{30%} |
|---|---|---|---|
| ttclid | string | <strong>仅网站事件可指定本字段。</strong><br><br>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>网站事件、应用事件、线下事件和 CRM 事件均可指定本字段。</strong> <br><br><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>| `"848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f"`|
| phone | string 或 string[] | <strong>网站事件、应用事件、线下事件和 CRM 事件均可指定本字段。</strong> <br><br><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> | `"9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd"` |
| external_id| string 或 string[] | <strong>仅网站事件和 CRM 事件可指定本字段。</strong> <br><br><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>| `"80fba0ae1c48e3978e43e4efc365e14e12ea0c830ba8ba5b9a2dafc7e3f2ab8b"` |
| ttp | string | <strong>仅网站事件可指定本字段。</strong> <br><br>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 | <strong>仅网站事件和应用事件可指定本字段。</strong> <br><br>用户设备的未经散列处理的公共 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>| `"203.0.113.1" "2001:0db8:85a3:0000:0000:8a2e:0370:7334"` |
| user_agent | string |<strong>仅网站事件和应用事件可指定本字段。</strong> <br><br> 用户设备的未经散列处理的用户代理。<br><br>为增加网站访客事件与 TikTok 广告的匹配率，建议同时传入 `ip` 和 `user_agent`。 | `"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"` |
| idfa | string | iOS IDFA（广告主标识符），<strong>仅应用事件可传入本字段。</strong><br><br>对于 iOS 14 及以上版本，请确保 IDFA 数据收集遵循 [Apple 的政策](https://developer.apple.com/app-store/user-privacy-and-data-use/)。<br><br>允许传入未经 SHA-256 散列处理或经SHA-256 散列处理的 IDFA：  <ul><li>对于未经 SHA-256 散列处理的 IDFA，所有字符必须为<strong>大写</strong>。</li><li>对于经SHA-256 散列处理的 IDFA，所有字符必须为<strong>小写</strong>，且散列处理前需<strong>去掉首尾空格</strong>。 </li></ul> | <ul><li>未经 SHA-256 散列处理的 IDFA: "`EA7583CD-A667-48BC-B806-42ECB2B48606"`</li><li>经 SHA-256 散列处理的 IDFA: `"70574fa9c8f498a7b2e5c8712b1126de7b1406fd02fdc591821c5bd33092fd1c"`</li></ul>|
| idfv | string | iOS IDFV（应用开发商标识符），<strong>仅应用事件可传入本字段。</strong>| |
| gaid | string | GAID（谷歌广告 ID），<strong>仅应用事件可传入本字段。 </strong><br><br>允许传入未经 SHA-256 散列处理或经SHA-256 散列处理的 GAID。<br>对于未经 SHA-256 散列处理或经SHA-256 散列处理的 GAID：<ul><li>所有字符必须为<strong>小写</strong>，且 </li><li>散列处理前需去掉<strong>首尾空格</strong>。</li></ul>| <ul><li>未经 SHA-256 散列处理的  GAID: `"aaaaaa-2222-1111-8787-809e92233ba0"`</li><li>经 SHA-256 散列处理的  GAID: `"0ebad966881e1eebffe69b3abf624631cf83ec9bf8cb3ce134c7c75c6d8ee7fc"`</li></ul>|
| locale | string | <strong>仅网站事件和应用事件可指定本字段。</strong> <br><br>BCP 47 语言标识符。<br><br>若想了解该标识符的详情，请查看[IETF BCP 47 标准语言代码](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)。  | `"en-US"`<br><br> `"zh-CN"` |
| att_status | string | <strong>仅应用事件可指定本字段。</strong> <br><br>用户的应用追踪权限。即用户是否授予您的应用访问应用相关数据的权限，以追踪用户及其设备。这是 iOS 独有字段。<br><br>枚举值：<ul><li> `AUTHORIZED`：用户已授权访问可用于追踪用户及其设备的应用相关数据。</li><li>`DENIED`：用户尚未通过 [Apple 的 AppTrackingTransparency 框架](https://developer.apple.com/documentation/apptrackingtransparency)授权访问可用于追踪用户及其设备的应用相关数据。<br>  若设置为此值，TikTok 将不会将应用事件里的个人信息数据（例如用户电子邮件地址/手机号）用于用户追踪。</li><li>`NOT_DETERMINED`：用户尚未收到允许访问应用相关数据来追踪用户及其设备的授权请求。</li><li>`RESTRICTED`：追踪用户及其设备的应用相关数据的授权处于限制状态。</li><li> `NOT_APPLICABLE`：iOS 版本低于14 或正在使用 Android 设备。</li></ul> | `"AUTHORIZED"` |

properties参数

与事件相关的订单和产品信息。提供这些信息可以帮助 TikTok 优化您的广告性能。

| 字段 {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|<strong>仅适用于应用事件和网站事件。</strong><br><br>用于表示与转化事件关联的客户细分群体的类别标签。<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%} | 描述{40%} | 示例{30%} |
|---|---|---|---|
| url {必填} | string | 事件发生所在的浏览器 URL，例如客户端 JavaScript 中的 `location.href`的值。 <br>建议使用完整的 URL，包括所有的 URL 参数。 | `"http://demo.mywebsite.com/purchase?v=helloworld"` |
| 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 参数。 | `"http://demo.mywebsite.com/purchase"` |

app参数

使用app参数与事件 API 2.0 分享有关广告主的应用的信息。app参数应仅在报告应用事件（event_source = app）时使用。

注意
使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。

|字段{20%}|类型{10%}|描述{70%}|
|---|---|---|
| app_id {+条件必填} | string | <strong>应用事件需指定本字段。</strong> <br><br>移动应用 ID。<ul><li>对于 iOS 应用，请使用在 App Store URL 中的应用 ID。<ul><li>示例：Apple Store URL：`https://apps.apple.com/us/app/angry-birds/id343200656`<ul><li> id = `"343200656"`</li></ul> </li></ul></li><li>对于在 Google Play 商店中的 Android 应用，请使用在 Google Play 商店 URL 中的应用 ID。<ul><li>示例：Google Play 商店 URL：`https://play.google.com/store/apps/details?id=com.rovio.angrybird`<ul><li> id = `"com.rovio.angrybirds"` </li></ul></li></ul></li><li>对于未在 Google Play 商店中的 Android 应用，请使用应用包名。</li></ul>|
| app_name | string | 应用名称。 |
| app_version | string | 应用版本号。<br><br> 示例：`"3.0.2"`。 |

使用ad参数与事件 API 2.0 分享有关广告主的应用的信息。ad参数应仅在报告应用事件或网站事件（event_source = app 或 web）时使用。

注意
使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的 TikTok 销售代表。

|字段{20%}|类型{10%}|描述{70%}|
|---|---|---|
| callback | string |  <strong>仅适用于应用事件。</strong><br><br>回调信息，用于帮助事件归因。 |
| campaign_id | string |  <strong>仅适用于应用事件。</strong><br><br>推广系列 ID。 |
| ad_id | string |  <strong>仅适用于应用事件。</strong><br><br>广告组 ID。 |
| creative_id | string |  <strong>仅适用于应用事件。</strong><br><br>广告 ID。 |
| is_retargeting | boolean |  <strong>仅适用于应用事件。</strong><br><br>用户是否是重定向（再营销）客户。 |
| attributed | boolean |  <strong>仅适用于应用事件。</strong><br><br>事件是否已归因。 |
| attribution_type | string |  <strong>仅适用于应用事件。</strong><br><br>归因类型。 |
| attribution_provider | string | <strong>仅适用于应用事件。</strong><br><br>归因服务提供商。 |
|attribution_share|float| <strong>仅适用于应用事件和网站事件。</strong><br><br>归因份额分数。<br>你为每次转化打的分数，代表 TikTok 在促成转化方面应获得的贡献比例。分数越高，表明 TikTok 对转化的贡献越大。<br><br>示例：<ul><li>0.0：无贡献。</li><li>0.5：部分贡献。</li><li>1.0：全部贡献。</li></ul>|

lead参数

使用lead参数与事件 API 2.0 分享有关 CRM 系统中线索的信息。lead参数应仅在报告 CRM 事件（event_source = crm）时使用。

|字段{20%}|类型{10%}|描述{70%}|
|---|---|
| lead_id {+条件必填} | string | 对于 CRM 事件必填。<br><br>TikTok 线索的 ID。<br> 从 TikTok 导出的线索均有对应的`lead_id`。<br> <br>若想获取线索 ID，可使用 [/page/lead/task/](1739052936772610.html) 和 [/page/lead/task/download/](1739053563877378.html) 接口下载线索，或从 TikTok 广告管理平台中的第一方 CRM 平台 Leads Center 导出线索。 |
| lead_event_source | string | 线索事件来源。<br>您可将本字段设置为您的 CRM 系统的名称，例如 HubSpot 或 Salesforce。 |

示例

报告网站事件

(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)

报告线下事件

(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": "offline",
  "event_source_id": "{{Offline-Event-Set-ID}}",
  "data": [
    {
      "event": "Purchase",
      "event_time": 1684574395,
      "user": {
        "email": ["848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f",
        "dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f"],
        "phone": ["2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea"]
      },
      "properties": {
        "order_id": "abc_xyz",
        "shop_id": "123abc",
        "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 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": "app",
  "event_source_id": "{{TIKTOK_APP_ID}}",
  "data": [
    {
      "event": "InstallApp",
      "event_time": 1687758765,
      "user": {
        "phone": "{{HASHED_PHONE}}",
        "email": "{{HASHED_EMAIL}}",
        "idfa": "{{IDFA}}",
        "idfv": "{{IDFV}}",
        "gaid": "{{GAID}}",
        "att_status": "AUTHORIZED",
        "locale": "en-US"
      },
      "app": {
        "app_id": "com.test.flyingsneakers",
        "app_name": "Flying Sneakers",
        "app_version": "3.0.2"
      },
      "ad": {
        "attributed": true,
        "callback": "{{CALLBACK}}",
        "campaign_id": "1700817380525057",
        "ad_id": "1700817380806706",
        "creative_id": "1700817378256945",
        "is_retargeting": false,        
        "attribution_type": "click_through"
      },
      "properties": {
        "currency": "USD",
        "value": 200.0,
        "content_type": "product",
        "contents": [
          {
            "price": 100.0,
            "quantity": 2,
            "content_id": "12345",
            "content_name": "Fancy-AirMax2.0 Black",
            "content_category": "Shoes - Running Shoes",
            "brand": "Fancy Sneakers"
          }
        ]
      }
    }
  ]
}'

(/code)

报告 CRM 事件

仅使用必填字段
(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": "crm",
  "event_source_id": "{{CRM-Event-Set-ID}}",
  "data": [
    {
      "event": "AddToCart",
      "event_time": 1687673101,
      "lead": {
        "lead_id": "{{lead_id}}"
      }
    }
  ]
}'

(/code)
使用必填和选填字段
(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": "crm",
  "event_source_id": "{{CRM-Event-Set-ID}}",
  "data": [
    {
      "event": "AddToCart",
      "event_time": 1687673101,
      "lead": {
        "lead_id": "{{lead_id}}",
        "lead_event_source": "Salesforce"
      }
      "user": {
        "external_id": "{{external_id}}",
        "phone": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
        "email": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b"
      },
      "event_id": "{{event_id}}",
    }
  ]
}'

(/code)

返回

注意
进行测试时，需关注 code 和 message 字段。若 code 的值非 0，则代表出现报错，message 字段将给出错误的具体描述。

|字段{30%}|类型{15%}|描述{55%}|
|-|-|-|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](https://business-api.tiktok.com/portal/docs/return-codes-appendix/v1.3)。|
|message |string|返回信息。更多信息参见[附录 - 返回码](https://business-api.tiktok.com/portal/docs/return-codes-appendix/v1.3)。|
|request_id|string| 请求的日志 ID，唯一标识一个请求。|
|data|object|返回数据。|

示例

(code curl http)
HTTPS/1.1 200 OK
{
  "code": 0, 
  "message": "OK", 
  "request_id": "{{request_id}}", 
  "data": {}
}
(/code)
← 事件 2.0Discovery →

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