資料層

資料層是 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() 呼叫，在評估所有其他待處理訊息之後，相關訊息就會排入佇列並進行處理。也就是說，任何更新後的資料層值，不保證會在下一個事件中使用。如要處理這類情況，您應在將事件推送至資料層時在訊息中新增事件名稱，然後使用自訂事件觸發條件監聽該事件名稱。

使用含有事件處理常式的資料層

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)

dataLayer.push 必須使用有效的 JavaScript 物件呼叫。所有資料層變數名稱都必須用引號括住。

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 代碼或代碼管理工具容器片段中的資料層參數值改成自選名稱。

<!-- 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>

自訂資料層方法

如果您將函式推送至資料層，系統會使用這組函式叫用這個函式，做為抽象資料模型。這個抽象資料模型可取得鍵值儲存庫並設定值，並且提供重設資料層的方法。

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

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

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