Monitoring API 開發人員指南

Monitoring API 可讓您建立工具來監控標記的行為和成效。方法是透過 addEventCallback Custom Template API 方法完成。這個方法可讓您指定事件回呼，系統會在事件結束時叫用該回呼。這個回呼功能會接收事件相關資訊，方便您自行建立代碼監控導入方式。您也可以將中繼資料加入標記，以便更精細地監控。

Monitoring API 支援多種監控用途，例如標記狀態、執行時間和中繼資料。這些監控像素的最終目標是將資料傳送到您選擇的端點。然後存取來自這個端點的記錄，以便收集監控資料。接著，該項資料會顯示在資訊主頁中，或用來觸發快訊系統。

代碼狀態

這個範例中顯示的代碼狀態技術會使用 addEventCallback 計算網頁上的代碼觸發狀態。這會重新擷取為事件觸發的所有代碼，並計算成功、失敗、擲回例外狀況或逾時的代碼數量。然後，這些總數會以查詢參數的形式加入監控像素網址。監控像素的網址如下：

https://www.example.com/monitoring?ctid=GTM-XXXXXX&success=4&failure=1&exception=1&timeout=0

您可使用以下程式碼範例設定像素網址：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let successCount = 0;
  let failureCount = 0;
  let exceptionCount = 0;
  let timeoutCount = 0;

  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry  = tagData[i];
    switch (entry.status) {
      case 'success':
        successCount++;
        continue;
      case 'failure':
        failureCount++;
        continue;
      case 'exception':
        exceptionCount++;
        continue;
      case 'timeout':
        timeoutCount++;
        continue;
    }
  }
  let url = 'https://www.example.com/monitoring?ctid=' + containerId +
      '&success=' + successCount +
      '&failure=' + failureCount +
      '&exception=' + exceptionCount +
      '&timeout=' + timeoutCount;
  sendPixel(url);
});
data.gtmOnSuccess();

執行時間

這項技巧會使用 addEventCallback，協助您收集代碼執行時間的相關資料。針對為這個事件觸發的每個代碼，系統會在像素網址中加入查詢參數 (內含代碼的 ID 和執行時間)。這會傳送類似以下的像素：

https://www.example.com/monitoring?ctid=GTM-XXXXXX&tag12=1200&tag50=400&tag1=6000

您可使用以下程式碼範例設定像素網址：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring?ctid=' + containerId;
  const tagData = eventData['tags'];
  const timingData = [];
  for (let i in tagData) {
    let entry = tagData[i];
    timingData.push('&tag' + entry['id'] + '=' + entry['executionTime']);
  }
  url += timingData.join('');
  sendPixel(url);
});
data.gtmOnSuccess();

中繼資料

您可以利用 Monitoring API 提供的基本資料，建構實用的資訊主頁。不過，在某些情況下，您可能只想監控一小部分的代碼。您可以前往「標記中繼資料」部分，在代碼定義中指定任意鍵/值組合，發生事件回呼時，這些值會包含在事件資料物件中。

舉例來說，將代碼加進新廣告活動的容器中。容器已有許多代碼，但您只想監控這個新代碼。

如要透過事件回呼識別這個標記，請在標記中加入中繼資料：

1. 在代碼定義中，依序按一下「進階設定」>「其他代碼中繼資料」。
2. 按一下「加入代碼名稱」加以勾選。
3. 在「代碼名稱的鍵」中輸入值。此範例使用「name」做為值。系統會在傳送的事件資料中加入代碼名稱。
4. 按一下「+新增中繼資料」，然後輸入「鍵」和「值」組合。此範例使用名為「group」的鍵，且值為「Campaign 2019」。
5. 使用 + 新增中繼資料，視需要新增其他鍵/值組合資料列。

在自訂範本中，開發人員可以檢查中繼資料中設定的值，藉此識別這個標記：

const addEventCallback = require('addEventCallback');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaignPixel?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['name'] === 'Conversion Pixel 2019') {
      url += '&status=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

這樣會產生類似下列的像素網址：

https://www.example.com/monitoring/campaignPixel?ctid=GTM-XXXXXX&status=success

然後視需要監控「廣告活動 2019」群組的所有代碼：

const addEventCallback = require('addEventCallback');
const encode = require('encodeUriComponent');
const sendPixel = require('sendPixel');

addEventCallback(function(containerId, eventData) {
  let url = 'https://www.example.com/monitoring/campaign2019?ctid=' + containerId;
  const tagData = eventData['tags'];
  for (let i in tagData) {
    let entry = tagData[i];
    if (entry['group'] === 'Campaign 2019') {
      url += '&' + encode(entry['name']) + '=' + entry['status'];
      break;
    }
  }
  sendPixel(url);
});
data.gtmOnSuccess();

這會產生類似下圖的監控像素：

https://www.example.com/monitoring/campaign2019?ctid=GTM-XXXXXX&Conversion%20Pixel%202019=failure