任务

本指南将介绍“任务”。这是一项高级功能,用于自定义 analytics.js 验证、构造和发送 Measurement Protocol 请求的方式。

概览

每次调用 send 命令时,analytics.js 都会执行一系列任务来验证和构造 Measurement Protocol 请求,并将该请求从用户的浏览器发送到 Google Analytics(分析)。下表将按执行顺序逐一说明其中每项任务:

任务名称 说明
customTask 默认情况下此任务不进行任何操作。重写可以提供自定义行为。
previewTask 如果网页的渲染只是用于生成 Safari 的“Top Sites”缩略图,则中止该请求。
checkProtocolTask 如果网页的协议不是 httphttps,则中止该请求。
validationTask 如果必填字段缺失或无效,则中止该请求。
checkStorageTask 如果跟踪器被配置为使用 Cookie 但用户的浏览器停用了 Cookie,则中止该请求。
historyImportTask 从 ga.js 和 urchin.js Cookie 导入信息,以便在网站迁移到 Universal Analytics 时保留访问者的历史记录。
samplerTask 根据此跟踪器的 sampleRate 设置对访问者进行抽样。
buildHitTask 构建 Measurement Protocol 请求字符串,并将其存储于 hitPayload 字段中。
sendHitTask 将存储于 hitPayload 字段中的 Measurement Protocol 请求传输到 Google Analytics(分析)服务器。
timingTask 根据此跟踪器的 siteSpeedSampleRate 设置,自动生成网站速度计时命中。
displayFeaturesTask 如果展示广告功能已启用并且尚未在广告功能 Cookie (_gat) 设置的超时时限内发送前一次命中,则将发送一次额外的命中。

每项任务都以 JavaScript 函数的形式实现,这些函数都接受一个模式参数作为输入信息。模式是一个简单的对象,可提供对 Analytics.js 字段参考中定义的任何字段的访问权限。

您可以使用标准跟踪器的 getset 方法来访问或替换任务。借助这些方法,您可以用自己的自定义函数来替换任务,也可以让您的自定义函数在现有任务之前或之后链式执行,以此来对现有功能进行补充。

实现

此节将介绍如何向现有任务添加新功能、用自定义代码来替换内置任务函数,或完全停用某个任务函数。

替换任务

要替换任务,您可以将其值 set 为执行不同操作的函数。替换任务常见的原因是测试您的 analytics.js 实现时进行功能存根

下面的代码使用将命中负载记录到控制台的函数替换 sendHitTask

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

向任务添加功能

要插入新功能,您可以让您的自定义任务函数在现有任务之前或之后链式执行。在以下示例中,sendHitTask 被一个自定义任务函数所替代,该函数会先调用原有 sendHitTask 函数来向 google-analytics.com/collection 发送正常请求信标,然后执行自定义代码来向本地服务器发送 Measurement Protocol 请求的副本。

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

中止任务流程

任务可以引发异常,以此来中止后续任务流程。如果会引发异常的任务在 sendHitTask 之前执行,则会阻止向 Google Analytics(分析)服务器发送 Measurement Protocol 请求。在以下示例中,我们会在用户浏览器中包含名为“testing”的 Cookie 并且其值为“true”时中止请求。

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

停用某个任务

要停用任意内置任务函数,请用 null 来替换该函数。

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');