← 返回目录
📁 Marketing API › Ad Measurement › Guides › Pixel

使用代码安装Pixel

使用须知

  • 您必须已经在事件管理平台上创建了一个Pixel，并且能够获取Pixel基础代码。您可以通过这篇帮助中心的文章，了解如何创建一个Pixel。
  • 您必须具备技术资源。
  • 您必须能够获取网站的源代码。

安装 Pixel

如果您已经创建了一个Pixel，但还未将其安装在网站上，您需要先完成Pixel安装，才能进行事件配置。 1. 直接从设置屏幕中获取Pixel基础代码，或者使用我们的基础代码模板。在使用模板之前，请使用您的Pixel ID替换占位符。

(code Javascript javascript)
// BASE CODE TEMPLATE:

<script>
//Part1
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};

//Part 2
  ttq.load('YOUR PIXEL ID WILL BE LOCATED HERE');
  ttq.page();
}(window, document, 'ttq');
</script>
(/code)

基础代码包含2个部分： * 第一部分：通用函数。 * 第二部分：包含ttq.load('{pixel ID占位符}')，能够根据特定Pixel的配置加载上下文。ttq.page()将报告一个页面视图事件，可用于验证Pixel代码安装情况。

  1. 将基础代码粘贴到网站标题部分的顶部，完成安装。网站标题以标签开头，以标签结尾。下面是一个示例：
(code Javascript javascript)
// Header example:
<!DOCTYPE html >
    <head>
          "INSERT TIKTOK PIXEL CODE HERE"
    </head>
</html>
(/code)

事件代码

在安装事件代码前，请确保您已经在上一步中正确安装了基础代码。如果没有基础代码，事件代码本身将无法运行。

通过事件代码，您能够报告访客完成转化时采取的具体行动或事件。例如，假如您经营的是一家电商公司，那么"添加到购物车"和"完成付款"对您来说便是很重要的监测事件。以下是TikTok Pixel和事件API目前支持的标准事件列表。

对于任何一个标准事件，您都可以发送参数，或有关访客行为的额外信息，如订单总金额或产品名称和类别。如果您不确定使用什么参数，请参考表格中的建议参数。

|事件{20%}|描述{35%}|事件代码{25%}|建议参数{20%}|
|---|---|---|
|添加付款信息|当访客在结账时添加支付信息时。|ttq.track('AddPaymentInfo')| |
|加入购物车|当访客将商品加入购物车时。|ttq.track('AddToCart')|content_type, quantity, description, content_id, currency, value|
|加入心愿单|当访客将商品加入心愿单时。|ttq.track('AddToWishlist')| |
| 提交申请|  当访客提交申请时。   | ttq.track('ApplicationApproval') |  |
|支付完成|当访客付款时。如下单和付款同时完成，TikTok 建议使用此类事件。|ttq.track('Purchase')|content_type, quantity, description, content_id, currency, value|
|完成注册|当访客进行注册时，比如注册账户。|ttq.track('CompleteRegistration')| |
|联系|当访客主动联系您时。|ttq.track('Contact')| |
| 定制商品 | 当访客定制商品时。 | ttq.track('CustomizeProduct') ||
|下载|当访客从您的网站下载内容时。|ttq.track('Download')| |
| 寻找位置 | 当访客试图寻找您的位置时。 | ttq.track('FindLocation') ||
|开始结账|当访客进入结账环节时。|ttq.track('InitiateCheckout')| |
| 预约 | 当访客预约与您的企业交谈或实地来访时。 | ttq.track('Schedule') ||
|搜索|当访客搜索内容时。|ttq.track('Search')|query|
|提交表单|当访客提交表单时。|ttq.track('Lead')| |
| 开始试用 |当访客开始试用时。 | ttq.track('StartTrial') | currency, value  |
| 提交申请| 当访客提交申请时。| ttq.track('SubmitApplication') |  |
|订阅|当访客在您的网站上执行订阅操作时，包括关注网站、订阅内容或付费订阅。|ttq.track('Subscribe')| |
|查看内容|当访客浏览特定页面时。TikTok建议监测影响业务的关键页面，比如产品比较页面、官方动态页面或产品发布页面等。|ttq.track('ViewContent')|content_type, quantity, description, content_id, currency, value|

注意
默认情况下，Pixel基础代码始终包括对网页浏览事件的监测，即监测访客登陆到您网站的时间。 因此，您不需要添加额外的事件代码来监测"页面浏览"。

安装事件代码

您可以在网页的头部和尾部<body>标签之间的任何地方调用ttq.track('')函数，可以是在网页加载时，也可以是在访客完成一个动作时（比如点击按钮）。

注意: 在下面的示例代码片段中，我们使用 "pixel_id_1"、"pixel_id_2 "和 "pixel_id_3 "作为占位符，以帮助说明。 请确保您在使用该代码时使用实际Pixel ID。

根据页面加载监测事件

如果您希望在访客完成购买后监测购买事件，您可以在确认购买页面上调用ttq.track('')函数（前提是确认购买页面加载这个基础代码）：

(code Javascript html)
<body>
  ...
  <script>
    ttq.instance('pixel_id_1').track('Purchase')
  </script>
  ...
</body>
(/code)

根据按钮点击监测事件

如果您希望在访客点击购买按钮时监测购买事件，您可以将ttq.track('')函数绑定至结账页面中的购买按钮：

(code Javascript html)
<button id="addToCartButton">Purchase</button>
<script type="text/javascript">
document.getElementById("addToCartButton").onclick = function(){
    ttq.track('AddToCart',{  
    contents: [
    {
      content_id: '301',
      content_name: 'dress',
      quantity: 1,
      price: 8,
    }],
    content_type: 'product',
    value: 8.0,
    currency: 'USD',  })
}
</script>
(/code)

参数

以下是TikTok Pixel和事件API支持的参数列表。参数可以与任何事件相配对。您可以通过描述了解如何使用这些参数。

|参数 {17%}|描述{28%} | 值类型{19%}|对于广告支出回报率 (ROAS) 是否为必填参数{12%}|对于视频购物广告是否为必填参数{12%}|对于价值优化 (VBO) 是否为必填参数{12%}|
|---|---|---|---|
|content_ids| 商品或内容的唯一 ID 或多个 ID 的列表。 <br>示例：`['987','654']`。 <br>推荐使用 `sku id` 或 `item_group_id`。若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。<br>本参数在视频购物广告场景为必填。 |必须为字符串数组。| |✅| |
|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| | ||
#|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|✅||✅|
|num_items|商品数量。|integer| | ||
|search_string|用户输入的用于搜索的文本字符串。|string| | ||
|description|商品或页面的描述。|string| | ||
|status|订单、商品或服务的状态。<br><p><span style="color:darkred"><b>注意</b></span>: 为了能将状态的变化分享给 TikTok，可能需要使用事件 API，具体取决于您对`status`的使用需求。|string| | ||

添加参数至事件代码

您可以使用ttq.track(event, [parameters]);添加参数。下面是单件商品和多件商品的添加到购物车事件的代码示例。

(code Javascript javascript)
//以添加到购物车为例
// 单件商品
ttq.track('AddToCart', {
   contents: [
    {
      content_id: '301',
      content_name: 'dress',
      quantity: 1,
      price: 8,
    }],
    content_type: 'product',
    value: 8.0,
    currency: 'USD',
});

// 多件商品
ttq.track('AddToCart', {
   contents: [
    {
      content_id: '301',
      content_name: 'dress',
      quantity: 1,
      price: 8,
    },
    {
      content_id: '401',
      content_name: 'dress',
      quantity: 1,
      price: 1.2,
    }],
    content_type: 'product',
    value: 9.2,
    currency: 'USD',
});
(/code)

在您的参数中使用动态值

您可以设置动态值，将与事件相关的动态值传递到TikTok。之后，此动态代码便会自动确定事件的正确值（例如购买价格）而不是使用设定值。

例如，如果访客登陆您的网站，并将一本书添加到他们的购物车中。此时的静态值或设定值如下：

(code Javascript html)
ttq.track('AddToCart', {
   contents: [
    {
      content_id: '301',
      content_name: 'book',
      quantity: 1,
      price: 8,
    }],
    content_type:'product',
    value: 8.0,
    currency: 'USD',
});
(/code)

要让这些值变为动态值，请使用代码替换掉设定值，这些代码会自动传递如“book”或“10.0”等正确值。

(code Javascript html)
ttq.track('AddToCart', {
   contents: [
    {
      content_id: DYNAMIC_CONTENT_ID_COMES_HERE,
      content_name: DYNAMIC_PRODUCT_NAME_COMES_HERE,
      quantity: DYNAMIC_QUANTITY_COMES_HERE,
      price: DYNAMIC_PRICE_COMES_HERE,
    }],
    content_type:'product',
    value: DYNAMIC_ORDER_VALUE_COMES_HERE,
    currency: 'USD',
});
(/code)

在用户拒绝监测时禁用 Pixel

如果用户拒绝监测，请确保您的网站有禁用 Pixel 的协议或代码。一旦 Pixel 被禁用，包括 Cookie，时间戳和事件在内的任何信息将不再被记录。如果您不确定如何在网站上运行此代码，可以采纳我们的建议：

  • 如果您正在使用谷歌代码管理器（Google Tag Manager），您可以参考Google's Consent Mode，自定义用户做出同意决策前后谷歌标签的行为。
  • 如果您没有技术资源或标签管理器，TikTok Pixel可与许多第三方同意管理平台整合。这些平台也可以提供技术资源和实施方案，包括横幅设计等。
  • 如果您有技术资源且不希望依赖第三方同意管理平台，TikTok 提供的 Pixel Cookie 同意模式可用于控制 Pixel 的 Cookie 使用。

验证 Pixel 和事件设置

在您完成设置后，可以采取以下方式来检查Pixel是否正常运行： 1. 安装 Pixel Helper chrome 扩展程序。 2. 使用我们事件管理器中的测试事件和诊断工具。 3. 预览广告。 4. 启用调试模式。

1. Pixel 自检器

TikTok Pixel 自检器 是一个 Chrome 扩展程序，它可以检查错误并为您的网站提供建议，帮助您验证和排查 Pixel 或事件 API 安装故障。

通过 TikTok Pixel 自检器，您可以在 Pixel、事件和参数实现（在特定情况下）层面进行详细诊断，从而对 Pixel 安装进行更深入的故障排查。 详情请参阅TikTok Pixel 自检器简介。

Pixel 自检器 为广告主提供了多个核心优势，包括： 1. Pixel 状态: 通过快速访问像素、事件和参数级别（某些情况下）的安装详细信息来验证 Pixel 实现。 2. 详细诊断: 通过查看错误消息和针对 Pixel 的和实现建议，排查常见的设置问题并提高 Pixel 性能。 Pixel 自检器 于 2021 年 3 月 4 日开始推出。在此处下载 Pixel 自检器。

2. 测试事件和诊断

在 TikTok广告管理平台中，点击工具 > 事件 > 数据来源，进入事件管理平台。选择任一 Pixel 或事件 API 连接，进入详情页，您会看到以下五个选项卡： - 概览: 验证网络监测设置并监测活动，快速获取网络监测详情。事件状态显示一个Pixel事件是否活跃或无近期活动，上次收到时间显示TikTok最近一次收到该事件的时间。 - 测试事件: 使用现场测试环境，实时测试网络事件，模拟网站在TikTok应用程序中的显示方式。 在扫描二维码（Pixel）或发送test_event有效负载（事件 API）后，您可以测试事件是否已由 TikTok正确设置，以及能否被 TikTok 正确接收。 - 诊断: 诊断功能可帮助您识别常见的设置错误，并根据建议实施解决方案，提高Pixel的表现。可通过诊断选项中的网页事件详情页面获取诊断。 - 操作日志: 查看此前对网页监测连接或配置事件所作的任何改变。操作日志包括操作日期、操作对象、活动类型、操作详情和操作员，帮助您高效排除问题。 - 设置：查看并管理 TikTok Pixel 的设置，包括自动高级匹配、Cookie 使用、强化数据回传、事件设置、事件 API 的访问令牌生成和合作伙伴平台。

若想了解如何使用诊断工具，请参考我们的帮助中心。

3. 调试模式

如果您在调试你的Pixel设置时需要更多的细节，您可以开启调试模式。 - 开启调试模式的两种方法： 1. 打开Sdk Link，运行document.cookie="pixel_debug=true; expires=Thu, 18 Dec 2043 12:00:00 GMT; path=/; SameSite=None; Secure"; 2. 刷新您的网站 - 检查调试信息 请先打开浏览器的控制台。之后Tiktok Pixel会在控制台输出调试日志。日志信息将以[TT]开头。例如：

关键节点的日志 - 当您调用ttq.load()时：

  • 当您调用 ttq.identify()或ttq.instance().identify()时：

  • 当您调用ttq.page()或ttq.track()或ttq.instance().track()时：

  • 当我们从cache或URL或bridge获得信息时：

常见问题

如何在我的网站上设置多个Pixel？

您可以参考下列包含3个Pixel基础代码的代码示例。在使用代码时，请用您的Pixel ID替换占位符。

(code Javascript html)
<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
}(window, document, 'ttq');

ttq.load('BRU69P41M9ALI4R4B2QG');
ttq.page();
</script>

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
}(window, document, 'ttq');

ttq.load('pixel_id_2');
ttq.page();
</script>

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=i,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;var a=document.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
}(window, document, 'ttq');

ttq.load('pixel_id_3');
ttq.page();
</script>
(/code)

如果我的网站上有多个Pixel，我该如何设置事件？ 在这种情况下，您需要考虑两种事件设置场景：

  1. 每个Pixel报告不同的事件
  2. 所有Pixel都报告相同的事件

请参考下面的示例代码，了解在这两种场景下如何设置事件：

场景1: 每个Pixel报告不同的事件

(code Javascript html)
<script>
function () {
/* xxxxx */

ttq.load('pixel_id_1')
ttq.page()
}()
</script>

<script>
function () {
/* xxxxx */ 

ttq.load('pixel_id_2')
ttq.page()
}()
</script>
<script>
function () {
/* xxxxx */

ttq.load('pixel_id_3')
ttq.page()
}()
</script>
ttq.instance('pixel_id_1').track('Purchase')
ttq.instance('pixel_id_2').track('Event 2')
ttq.instance('pixel_id_3').track('Event 3')
(/code)

场景2: 所有Pixel都报告相同的事件

(code Javascript html)
<script>
function () {
/* xxxxx */

ttq.load('pixel_id_1')
ttq.page()
}()
</script>

<script>
function () {
/* xxxxx */

ttq.load('pixel_id_2')
ttq.page()
}()
</script>

<script>
function () {
/* xxxxx */

ttq.load('pixel_id_3')
ttq.page()
}()
</script>

ttq.track('Purchase') // it will report three Purchase events for pixel_1 and pixel_2 and pixel_3
(/code)

在这个场景下, ttq.track('Purchase')与下列代码行相同：

(code Javascript javascript)
ttq.instance('pixel_id_1').track('Purchase')
ttq.instance('pixel_id_2').track('Purchase')
ttq.instance('pixel_id_3').track('Purchase')
(/code)

因为ttq.track()将报告所有已安装的Pixel事件。

← Pixel Cookie 同意模式CSP 配置 →

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