← 返回目录
📁 Marketing API › Ad Measurement › Guides › Google Tag Manager (GTM) Integration

使用数据层设置 TikTok 事件

数据层是 Google 跟踪代码管理器和 gtag.js 用于向代码传递信息的对象。您的网站代码可以通过使用 Google 代码或跟踪代码管理器 JavaScript API（即 gtag() 或 dataLayer.push()）与数据层交互，从而存储或发送数据。

我们开发了两个模板，即 TikTok Pixel 模板和 TikTok 事件 API 模板，用于解析数据层事件并通过 Pixel 和事件 API将事件发送至 TikTok。

注意
若您计划使用数据层将信息传递给代码，强烈建议使用 TikTok 事件管理平台中的交互式流程来设置 Pixel 或事件API 与 Google 跟踪代码管理器的集成。该流程会自动安装模板以及处理和发送数据层事件至 TikTok 所需的所有必要代码、变量和触发器。若想了解更多详情，请参阅：

TikTok 模板识别的事件和参数与 Google 推荐的一致。若想了解推荐事件类型和参数的详情，请参阅推荐事件和常见事件数据。

注意
如果您已经按照 Google 的指南（即推荐事件和常见事件数据）设置了事件，以使用 Google Analytics（分析）4 （GA4）度量您的网站，TikTok 模板将自动检测相同的事件或参数并转换为 TikTok 的标准事件或参数。

本文档涵盖以下内容： - 设置数据层事件的前提条件 - purchase 事件示例 - 数据层事件结构概述，包括推荐的事件类型和参数

前提条件

一个简单的 purchase 事件

以下示例用于展示运作原理。假设您想向 TikTok 发送一个 Purchase 事件，当用户在您的网站上进行购买操作时，您的网站的 JavaScript 代码应通过 Google 跟踪代码管理器数据层触发一个 purchase 事件。TikTok 模板随后将解析此事件并将其作为 Purchase 事件发送给 TikTok。

(code Javascript javascript)
// Google Tag example
gtag('event', 'purchase', {
  transaction_id: 'T_12345',
  value: 200.0,
  currency: 'USD',
  user_data: {
    sha256_email_address: '0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b',
    sha256_phone_number: '123456405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b',
    address: {
      sha256_first_name: '4f23798d92708359b734a18172c9c864f1d48044a754115a0d4b843bca3a5332',
      sha256_last_name: 'fd53ef835b15485572a6e82cf470dcb41fd218ae5751ab7531c956a2a6bcd3c7',
      city: 'City Town',
      region: 'CA',
      postal_code: '54321',
      country: 'US'
    }
  },
  items: [
    {
      item_id: 'SKU_12345',
      item_name: 'Fancy-MaxSpeed2.0 Black',
      item_brand: 'Fancy Sneakers',
      item_category: 'Shoes - Running Shoes',
      price: 100.0,
      quantity: 2
    }
  ],
  tt_external_id: 'b9c5fdaea74ee1c31705b764389895371b8d416c5cae8740e7f89082a9fcdc0a',
  tt_content_type: 'product'
});
(/code)

(code Javascript javascript)
// Tag Manager example
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'purchase',
  user_data: {
    sha256_email_address: '0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b',
    sha256_phone_number: '123456405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b',
    address: {
      sha256_first_name: '4f23798d92708359b734a18172c9c864f1d48044a754115a0d4b843bca3a5332',
      sha256_last_name: 'fd53ef835b15485572a6e82cf470dcb41fd218ae5751ab7531c956a2a6bcd3c7',
      city: 'City Town',
      region: 'CA',
      postal_code: '54321',
      country: 'US'
    }
  },
  ecommerce: {
    transaction_id: 'T_12345',
    value: 200.0,
    currency: 'USD',
    items: [
      {
        item_id: 'SKU_12345',
        item_name: 'Fancy-MaxSpeed2.0 Black',
        item_brand: 'Fancy Sneakers',
        item_category: 'Shoes - Running Shoes',
        price: 100.0,
        quantity: 2
      }
    ]
  },
  tt_external_id: 'b9c5fdaea74ee1c31705b764389895371b8d416c5cae8740e7f89082a9fcdc0a',
  tt_content_type: 'product'
});
(/code)

以事件 API 集成为例，以下是发送到 TikTok 事件 API 的示例事件的有效负载。若想了解具体参数的详情，请参阅事件 API 参数。

(code Javascript javascript)
{
  "event_source": "web",
  "event_source_id": "{{PIXEL-CODE}}",
  "data": [
    {
      "event": "Purchase",
      "event_time": 1714176177,
      "user": {
        "phone": "0c7e6a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
        "email": "123456405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
        "external_id": "b9c5fdaea74ee1c31705b764389895371b8d416c5cae8740e7f89082a9fcdc0a",
        "first_name": "4f23798d92708359b734a18172c9c864f1d48044a754115a0d4b843bca3a5332",
        "last_name": "fd53ef835b15485572a6e82cf470dcb41fd218ae5751ab7531c956a2a6bcd3c7",
        "city": "citytown",
        "state": "ca",
        "country": "us",
        "zip_code": "20f3765880a5c269b747e1e906054a4b4a3a991259f1e16b5dde4742cec2319a"
      },
      "properties": {
        "currency": "USD",
        "value": 200.0,
        "content_type": "product",
        "contents": [
          {
            "price": 100.0,
            "quantity": 2,
            "content_id": "12345",
            "content_name": "Fancy-MaxSpeed2.0 Black",
            "content_category": "Shoes - Running Shoes",
            "brand": "Fancy Sneakers"
          }
        ]
      }
    }
  ]
}
(/code)

事件名称映射

在使用 Google 跟踪代码管理器数据层设置 TikTok 事件时，您需要直接发送 Google Analytics 推荐的事件名称。TikTok Pixel 和事件 API 模板将自动把它们映射为相应的 TikTok 标准事件名称。

如果某个 Google Analytics 事件名称未在以下映射表中列出，则将被视为 TikTok 自定义事件。详细了解 TikTok 支持的事件和 GA4 推荐事件。

| TikTok 标准事件名称 {30%}| Google Analytics 事件名称{60%} |
|---|---|
| `AddPaymentInfo` | `add_payment_info` |
| `AddToCart` | `add_to_cart` |
| `AddToWishlist` | `add_to_wishlist` |
| `Purchase` | `purchase` |
| `CompleteRegistration` | `sign_up` |
| `InitiateCheckout` | `begin_checkout` |
| `Pageview` | `page_view` |
| `Search` | `search` |
| `ViewContent` | `view_item` |

对于下列没有相应的 GA4 推荐事件名称的 TikTok 标准事件名称，您可以在设置事件时直接发送 TikTok 事件名称。 - Contact - Download - Lead - Subscribe

为了让 TikTok Pixel 和事件 API 模板能够自动转换 GA4 推荐事件名称，您需要在 TikTok Pixel 代码中将 Event Name（事件名称）设置为 Google 跟踪代码管理器内置的 {{Event}} 变量 ，并在 TikTok 事件 API 代码中将 Event Name（事件名称）设置为 Google 跟踪代码管理器内置的 {{Event Name}} 变量。

网站事件参数

在使用 Google 跟踪代码管理器数据层配置事件参数时，您需要遵循 GA4 推荐事件和 Google 跟踪代码管理器常见事件数据。TikTok Pixel 模板和事件 API 模板将自动将 Google 跟踪代码管理器和 GA4 参数映射到相应的 TikTok 参数。详细了解 TikTok Pixel 参数和事件 API 参数。

产品数据

若您在推广某一网站售卖的商品，商品信息不可或缺。发送完整的商品信息使度量和优化成为可能，例如通过启用用于商业场景的 TikTok 视频购物广告，价值优化，以及广告支出回报率（ROAS）追踪。

若想了解推荐的 Google Analytics 参数详情，请参阅 GA4 推荐事件。

TikTok 参数 Google Analytics 参数 对于 ROAS 或价值优化是否为必填参数 对于视频购物广告是否为必填参数
Google 代码
- gtag() API		 跟踪代码管理器
- dataLayer.push() API
value value ecommerce.value ✅
currency currency ecommerce.currency ✅
content_type tt_content_type tt_content_type ✅
contents items ecommerce.items
contents[].price items[].price ecommerce.items[].price
contents[].content_id items[].item_id ecommerce.items[].item_id ✅
contents[].content_category items[].item_category ecommerce.items[].item_category
contents[].content_name items[].item_name ecommerce.items[].item_name
contents[].quantity items[].quantity ecommerce.items[].quantity
contents[].brand items[].brand ecommerce.items[].brand

用户数据

若想利用高级匹配功能，从而帮助您通过与 TikTok 上的用户进行匹配来优化 TikTok 广告并提高效果，您可以发送以下用户信息。

若想了解 Google 跟踪代码管理器数据层参数的详情，请参阅 Google 跟踪代码管理器常见事件数据。

TikTok 事件参数 Google 跟踪代码管理器数据层参数
email
  • user_data.email_address
    • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
  • user_data.sha256_email_address
  • phone_number（用于 Pixel）
  • phone（用于事件 API）
  • user_data.phone_number
    • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
  • user_data.sha256_phone_number
external_id tt_external_id
  • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
  • 查看设置外部 ID了解详情。
first_name
  • user_data.address.first_name
    • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
  • user_data.address.sha256_first_name
last_name
  • user_data.address.last_name
    • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
  • user_data.address.sha256_last_name
city user_data.address.city

用户所在地址的城市信息。
state user_data.address.region

用户所在地址的州或区域信息。
country user_data.address.country

用户所在地址的国家或地区代码。
zip_code
  • user_data.address.postal_code
    • 该值将先进行 SHA256 散列处理，随后发送至 TikTok。
    • 对于美国邮政编码，只会向 TikTok 发送（经散列处理的）前五位数字。

将数据层事件发送至服务器代码

注意
如果您使用事件管理平台的交互式流程（推荐做法）设置事件 API 集成，您可以跳过以下设置步骤。这是因为交互式流程将自动安装 TikTok 事件 API 模板和所有其他必要的代码、变量和触发器，以便将事件发送至您的服务器容器。

对于事件 API 集成，将数据层事件（通过 gtag() 或 dataLayer.push() API 触发的事件）转发到已安装 TikTok 事件 API 模板代码的服务器容器中十分重要。要实现这一点，您需要设置 Google 代码、GA4 事件代码和一些额外变量。

设置 Google 代码

在您的网站容器中，添加一个Google 代码。若您已经设置了服务器端代码植入并且已有一个已配置了server_container_url 的 Google 代码，您可以重复使用同一 Google 代码。

在您的 Google 代码中，将 server_container_url设置为您的代码植入服务器，并将触发器设置为在All Pages（所有页面）上触发。了解详情。

设置 GA4 事件代码

在您的网站容器中，添加一个 Google Analytics（分析）：GA4 事件代码。

在您的Google Analytics（分析）：GA4 事件代码中，将 Event Name（事件名称）设置为内置的 {{Event}} 变量。

随后您需要配置 GA4 事件参数。

GA4 事件参数

  • 若您的网站配置了推荐的 GA4 数据层事件结构（请参阅网站事件参数中的说明），请根据您集成的具体 API（gtag() 或 dataLayer.push()）在 Google Analytics（分析）：GA4 事件代码中配置以下映射。GA4 事件参数指定将从网站容器转发至代码植入服务器上的服务器容器的数据参数和相应值。
  • 若您的网站配置了自定义结构，您需要在 TikTok 模板中使用 Parameter Override（参数覆盖）来手动配置 TikTok 事件参数。
| GA4 事件参数{20%} | 提示{20%}| <code>gtag()</code> API 中的值 {30%}| <code>dataLayer.push()</code> API 中的值 {30%}|
|---|---|---|---|
| `first_party_collection` | 若您想通过事件 API 将`user_data` 发送至 TikTok，需将 `first_party_collection` 设置为 `true`。 | `true` |`true`|
| `user_data`  | | 变量类型：数据层变量 <br>变量名称：`eventModel.user_data` | 变量类型：数据层变量 <br> 变量名称：`user_data` |
| `tt_external_id` |  | 变量类型：数据层变量 <br>变量名称：`eventModel.tt_external_id`| 变量类型：数据层变量<br> 变量名称：`tt_external_id`|
| `value` |  | 变量类型：数据层变量 <br>变量名称：`eventModel.value`| 变量类型：数据层变量<br> 变量名称：`ecommerce.value`|
| `currency`|   | 变量类型：数据层变量<br>变量名称：`eventModel.currency` | 变量类型：数据层变量<br>变量名称：`ecommerce.currency` |
| `tt_content_type` |  | 变量类型：数据层变量<br>变量名称：`eventModel.tt_content_type`  | 变量类型：数据层变量<br> 变量名称：`tt_content_type` |
| `tt_contents` | 若您想发送一个非 GA4 推荐事件的商品数据或不支持`items`参数的事件数据，请指定 `tt_contents`。[详细了解 GA4 推荐事件的配置](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtag&hl=zh-cn)。 | 变量类型：自定义 Javascript <br>`function() &#123; <br> &nbsp;&nbsp;&nbsp;&nbsp;var tt_contents = window.google_tag_manager[&#123;&#123;Container ID&#125;&#125;].dataLayer.get('eventModel.items');<br>&nbsp;&nbsp;&nbsp;&nbsp;return JSON.stringify(tt_contents); <br> } `<br> 将 `tt_contents` 参数转换为 JSON 字符串，因为它是 TikTok 定义的 GA4 JSON 参数。|变量类型：自定义 Javascript <br>`function() &#123; <br> &nbsp;&nbsp;&nbsp;&nbsp;var tt_contents = window.google_tag_manager[&#123;&#123;Container ID&#125;&#125;].dataLayer.get('ecommerce.items');<br>&nbsp;&nbsp;&nbsp;&nbsp;return JSON.stringify(tt_contents); <br> } `<br> 将 `tt_contents` 参数转换为 JSON 字符串，因为它是 TikTok 定义的 GA4 JSON 参数。|
| `event_id`  |  | 变量类型：自定义 Javascript <br> 请查看<a href="#item-link-如何设置事件去重">如何设置事件去重</a>。 | 变量类型：自定义 Javascript <br>  请查看<a href="#item-link-如何设置事件去重">如何设置事件去重</a>。 |

您需要启用发送电子商务数据并将 Data Layer（数据层）设置为数据源。

最后，为您的 GA4 事件代码指定一个触发器。在大多数情况下，您可以将触发器设置为在所有自定义事件上触发，并将事件名称匹配规则设置为正则表达式 .+ 。

配置示例

以下是一个完成上述设置的 Google Analytics（分析）：GA4 事件代码的配置示例：

如何设置事件去重

注意
若您使用推荐的事件管理平台交互式流程同时设置 Pixel 和事件 API 集成，将自动为您配置事件 ID 去重。

若要设置事件去重，您可以将 Google 跟踪代码管理器的一个自定义 JavaScript 变量配置为您的event_id。此变量有助于对 TikTok Pixel 和事件 API 事件进行去重。详细了解事件去重。

生成相同事件的 event_id 的方法之一是使用 Google 跟踪代码管理器数据层的默认值，即代码加载时间（start）和唯一事件序列 ID（uniqueEventId）。

若要设置事件 ID 去重，请按照以下步骤进行操作： - 在您的网站容器的 TikTok Pixel 代码中，导航至 Parameter Override（参数覆盖）> Deduplication Configuration（去重配置） > Event ID（事件 ID），将该变量设置成 Event ID 参数。 - 在您的网站容器的 Google Analytics（分析）：GA4 事件代码中，将同一个变量设置成 event_id 事件参数。

验证事件设置

在 Pixel 或事件 API 模板中配置 TikTok 事件和参数后，您可以按照验证跟踪代码管理器的设置的步骤来验证设置。

获取支持

若您遇到任何需要支持的问题，请在相应的 GitHub 项目中提交议题： - TikTok Pixel 模板 GitHub - TikTok 事件 API 模板 GitHub

← 同时设置 TikTok Pixel 和事件 API仅设置 TikTok 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 每日平台更新简报 →