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. 按一下「+Add Metadata」，然後輸入「鍵」和「值」組合。本範例使用名為「group」的鍵以及「廣告活動 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