資料層

資料層是 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>

資料層資訊的處理方式

容器載入時，代碼管理工具會開始處理所有已加入佇列的資料層推送訊息。代碼管理工具會依據先進先後順序處理訊息：系統會按照收到順序，逐一處理每則訊息。如果訊息是事件，觸發條件中會觸發所有符合觸發條件的代碼，直到代碼管理工具的訊息移到下一則訊息之前。

如果 gtag() 或 dataLayer.push() 呼叫是由網頁、自訂範本或自訂 HTML 標記中的程式碼所送出，相關的訊息就會排入佇列，並在系統評估完所有其他待處理訊息後加以處理。這表示對下一個事件來說，不保證會有最新的資料層值可用。如要處理這些情況，您應將事件名稱新增至訊息，因為該事件會推送至資料層，然後透過自訂事件觸發條件監聽該事件名稱。

重要事項： 請勿使用自訂 HTML 標記來部署 gtag.js 程式碼，請改用代碼管理工具的 Google Ads、Analytics (分析) 和 Floodlight 代碼。

重要事項： 請勿使用代碼管理工具中的 HTML同意聲明設定。由於必須先套用同意聲明設定，才能在代碼管理工具容器中觸發相關代碼，因此必須套用代碼管理工具 Consent API 以設定預設和更新行為。使用 Tag Manager Consent API 即可確保在資料層中任何已排入佇列的項目之前處理同意聲明更新，讓同一個事件觸發的所有代碼都具有相同的同意聲明狀態。

重點： 您可以使用 Google Tag Assistant 檢查事件鏈中任何時間點的資料層狀態。

搭配事件處理常式使用資料層

dataLayer 物件會使用 event 指令來啟動事件傳送程序。

當使用者與網站元素互動時，Google 代碼和代碼管理工具會使用名為 event 的特殊資料層變數，用來觸發代碼。舉例來說，您可以在使用者按下購物確認按鈕時觸發轉換追蹤代碼。每次使用者與網站元素 (例如連結、按鈕、捲動等) 互動時，系統就會呼叫事件。

在事件發生時，呼叫 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 物件。

自訂資料層方法

如果您將函式推送至資料層，系統就會透過這個設定叫用該抽象資料模型。這個抽象資料模型可取得鍵/值並將值設為鍵/值，並提供重設資料層的方式。

重要事項： 如要使用自訂資料層方法，您必須使用 .push 將資料直接傳送至 dataLayer 變數。如果您使用 gtag，系統會將該函式解讀為無效指令並忽略。

set

抽象資料模型上的 set 函式可讓您設定透過 get 擷取的值。

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

get

抽象資料模型上的 get 函式可讓您擷取設定的值。

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

重設

抽象資料模型上的 reset 函式可讓您重設資料層中的資料。這最適合用於會保持開啟的頁面，且資料層大小會隨時間增加。如要重設資料層，請使用以下程式碼：

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