数据层

数据层是一个对象，供 Google 跟踪代码管理器和 gtag.js 用来将信息传递给代码。您可以通过数据层传递事件或变量，然后设置根据变量值进行触发的触发器。

例如，在 purchase_total 的值大于 100 元时触发再营销代码；或者设置根据具体事件进行触发的触发器，例如，在用户点击按钮时，您的数据层可以配置为向代码传递该数据。数据层对象结构化为 JSON。例如：

{
  event: "checkout_button",
  gtm: {
    uniqueEventId: 2,
    start: 1639524976560,
    scrollThreshold: 90,
    scrollUnits: "percent",
    scrollDirection: "vertical",
    triggers: "1_27"
  },
  value: "120"
}

Google 代码旨在以井然有序且可预测的方式轻松引用添加到数据层的信息，而不是解析变量、交易信息、网页类别及其他分散在网页上的信号。填充了变量及关联值的数据层实现将有助于确保您的代码在需要时可以使用相关数据。

安装

对于适用于网页的跟踪代码管理器安装，您必须创建数据层。下面突出显示的代码表示在加载跟踪代码管理器之前数据层的建立位置。

<script>
window.dataLayer = window.dataLayer || [];
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

在标准 gtag.js 实现（即代码从产品中复制并添加到网页）中，系统提供了用于建立数据层的代码。在自定义的 Google 代码实现中，您需要在脚本的开头添加数据层代码，如下面突出显示的示例所示：

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments)};
  gtag('js', new Date());

  gtag('config', 'TAG_ID');
</script>

数据层信息的处理方式

当加载容器时，跟踪代码管理器会开始处理所有已加入队列的数据层推送消息。跟踪代码管理器按照先进先出的原则处理消息：按照收到消息的顺序，一次处理一条消息。如果消息是一个事件，它会触发符合相应触发条件的所有代码，然后跟踪代码管理器会继续处理下一条消息。

如果网页上、自定义模板或自定义 HTML 标记中的代码调用了 gtag() 或 dataLayer.push()，则相关消息将排入队列，并在完成对所有其他待处理消息的评估后进行处理。这意味着，任何更新后的数据层值均不保证可用于下一个事件。为处理此类情况，您应在将消息推送到数据层时为其添加事件名称，然后利用自定义事件触发器来监听该事件名称。

重要提示：请勿使用自定义 HTML 标记部署基于 gtag.js 的代码。正确做法是，使用跟踪代码管理器提供的用于 Google Ads、Google Analytics（分析）和 Floodlight 的原生跟踪代码模板。

重要提示：请勿使用自定义 HTML 标记配置跟踪代码管理器中的用户意见征求设置。由于需要在相关代码在跟踪代码管理器容器中触发之前应用用户意见征求设置，因此您必须应用 Tag Manager Consent API 来配置默认的行为和更新行为。使用 Tag Manager Consent API 可确保在数据层中任何已排入队列的项目之前处理用户意见征求更新，以便同一事件触发的所有代码均具有相同的同意情况。

要点：您可以使用 Google Tag Assistant 在事件链中的任何一点检查数据层的状态。

将数据层与事件处理脚本配合使用

dataLayer 对象使用 event 命令来启动事件的发送。

Google 代码和跟踪代码管理器会使用一个名为 event 的特殊数据层变量，该变量可供 JavaScript 事件监听器用来在用户与网站元素进行互动时触发代码。例如，您可能需要在用户点击购买确认按钮时触发转化跟踪代码。每当用户与链接、按钮、滚动条等网站元素互动时，系统就可能会调用相应事件。

此功能通过在事件发生时调用 dataLayer.push() 来实现。使用 dataLayer.push() 发送事件的语法如下：

dataLayer.push({'event': 'event_name'});

其中，event_name 是描述事件的字符串，如 'login'、purchase 或 search。

您可以使用 dataLayer.push() 在要衡量的操作发生时发送事件数据。例如，若要在用户点击按钮时发送事件，可以修改该按钮的 onclick 处理脚本以调用 dataLayer.push()：

<button onclick="dataLayer.push({'event': 'login'});">Button 1</button>

您可以动态地向数据层推送数据层变量来捕获各种信息，例如在表单中输入或选择的值、与访问者正在播放的视频相关联的元数据、访问者自行指定的产品（例如汽车）颜色、所点击链接的目标网址等。

和事件一样，此功能也是通过调用 push() API 实现的，不过这次是添加或替换数据层中的数据层变量。设置动态数据层变量的基本语法如下：

dataLayer.push({'variable_name': 'variable_value'});

其中 'variable_name' 和 'variable_value' 均为字符串，前者表示要设置的数据层变量的名称，后者表示要设置或替换的数据层变量的值。

例如：要设置一个数据层变量以便在访问者与产品定制工具互动时捕获颜色偏好，可以推送以下动态数据层变量：

dataLayer.push({'color': 'red'});

一次推送多个变量

您可以一次推送多个变量和事件：

dataLayer.push({
  'color': 'red',
  'conversionValue': 50,
  'event': 'customize'
});

重要提示：如果您将与现有变量同名的变量推送到数据层，则现有值会被新值覆盖。

保留数据层变量

若要在各个网页之间保留数据层变量，请在数据层实例化（在每次网页加载时）之后调用 dataLayer.push()，然后将变量推送到数据层。如果您希望在容器加载时将这些数据层变量提供给跟踪代码管理器，则可以在跟踪代码管理器容器代码上方添加 dataLayer.push() 调用，如下所示。

<script>
window.dataLayer = window.dataLayer || [];

dataLayer.push({
 'event': 'Pageview',
 'pagePath': 'https://www.googleanalytics.dev/pancakes',
 'pageTitle': 'Pancake Event Signup',
 'visitorType': 'customer'
});
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

只要访问者依然在当前网页上，数据层对象中声明的每个变量就会持续存在。必须在网站每个网页上的数据层中声明与各个网页都相关的数据层变量，例如 visitorType。尽管您不需要在每个网页的数据层中都放置同一组变量，但应该采用统一的命名惯例。也就是说：如果您在注册页上使用名为 pageCategory 的变量设置页面类别，那么在产品页和购买页上也应使用 pageCategory 变量。

问题排查

下面提供了一些有关数据层问题排查的提示：

请勿覆盖 window.dataLayer 变量：当您直接使用数据层时（例如 dataLayer = [{'item': 'value'}])，它会覆盖 dataLayer 中的任何现有值。安装跟踪代码管理器时，应使用 window.dataLayer = window.dataLayer || [];，在源代码中尽可能靠上的位置（容器代码段的上方）实例化数据层。声明 dataLayer 后，可以使用 dataLayer.push({'item': 'value'}) 向数据层添加更多值，如果需要在网页加载时将这些值提供给跟踪代码管理器，那么 dataLayer.push() 调用也需要位于跟踪代码管理器容器代码的上方。

dataLayer 对象名称区分大小写：如果您尝试推送存在大小写错误的变量或事件，推送将会失败。

datalayer.push({'pageTitle': 'Home'});    // Bad (datalayer in lowercase)
dataLayer.push({'pageTitle': 'Home'});    // Good (dataLayer in camel case)

必须使用有效的 JavaScript 对象调用 dataLayer.push。所有数据层变量名都应该加引号。

dataLayer.push({new-variable: 'value'});      // Bad - no quote marks
dataLayer.push({'new-variable': 'value'});    // Good - proper quote marks

确保变量名称在各网页之间保持一致：如果您针对同一概念在不同的网页中使用了不同的变量名称，您的代码将无法在所需的全部位置以一致的方式触发。

不好的做法：

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitor_type': 'high-value'});

良好的做法：

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitorType': 'high-value'});

重命名数据层

由 Google 代码或跟踪代码管理器启动的数据层对象的默认名称为 dataLayer。如果您希望为自己的数据层使用其他名称，可以使用您选择的名称修改 Google 代码或跟踪代码管理器容器代码段中的数据层参数值。

gtag.js

将名为“l”的查询参数添加到网址中，以设置新的数据层名称，例如 l=myNewName。将 Google 代码段中出现的所有 dataLayer 都更新为新名称。

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID&l=myNewName"></script>
<script>
  window.myNewName = window.myNewName || [];
  function gtag(){myNewName.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'TAG_ID');
</script>

跟踪代码管理器

将容器代码段中的数据层参数值（下文中突出显示的部分）替换为您选择的名称。

重要提示：请勿替换未突出显示的参数值。

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','myNewName','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

重命名后，您必须调整对数据层的所有引用（即在相应代码段上方声明数据层时以及使用 .push() 命令将事件或动态数据层变量推送到数据层时进行的引用），使它们体现您自行指定的数据层名称：

<script>
  myNewName = window.dataLayer || [];
  myNewName.push({'variable_name': 'variable_value'});
</script>

注意：每个网页仅支持一个 dataLayer 对象。

自定义的数据层方法

如果将一个函数推送到数据层，则在调用该函数时会将数据层设置为一个抽象数据模型。此抽象数据模型可以使用 get 函数获取值，以及通过 set 函数将值存储到键值对存储区，此外还提供了一个重置数据层的方法。

重要提示：为了使用自定义的数据层方法，您必须使用 .push 将数据直接发送到 dataLayer 变量。如果您使用 gtag，则该函数将被解释为无效的命令并被忽略。

set

通过抽象数据模型的 set 函数，您可以设置值，以便通过 get 检索这些值。

window.dataLayer.push(function() {
  this.set('time', new Date());
});

get

通过抽象数据模型的 get 函数，您可以检索由 set 函数设置的值。

window.dataLayer.push(function() {
  const existingTime = this.get('time');
  if (existingTime !== null) {
    // Change behavior based on whether or not this value exists...
  } else {
    // ...
  }
})

reset

通过抽象数据模型的 reset 函数，您可以重置数据层中的数据。对于将保持打开状态且数据层大小会随时间不断增长的网页，这非常有用。若要重置数据层，请使用以下代码：

window.dataLayer.push(function() {
  this.reset();
})