注意:此开发者网站正在向 developers.google.com/tag-platform 迁移,2021 年 9 月 30 日起将会进行重定向

Monitoring API 开发者指南

利用 Monitoring API,您可以构建工具以监控代码的行为和性能。这是通过 addEventCallback 自定义模板 API 方法完成的。此方法用于指定要在事件结束时调用的事件回调函数。该回调函数将接收事件相关信息,您可根据这些信息创建自己的代码监控方案。您还可以向代码添加元数据,用于进行更精细的监控。

Monitoring API 可支持多种监控用例,例如代码状态、执行时间和元数据。这些监控像素的最终目标是将数据发送到您选择的端点。之后来自此端点的日志便可供访问以收集监控数据,而收集到的数据可以显示在信息中心内或用于触发警报系统。

代码状态

此示例中显示的“代码状态”技术使用 addEventCallback 来记录页面上代码的触发状态。该技术会遍历针对相应事件触发的所有代码,并统计成功、失败、引发异常或超时这几类代码的数量。之后这些总数会作为查询参数添加到监控像素网址中。监控像素的网址类似于以下网址:

https://www.example.com/monitoring?ctid=GTM-ABCXYZ&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-ABCXYZ&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-ABCXYZ&status=success

如果需要,您可以接着监控“Campaign 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-ABCXYZ&Conversion%20Pixel%202019=failure