向 Google Analytics(分析)发送数据

JavaScript 衡量代码段的最后一行在 ga() 命令队列中添加了一条 send 命令,以向 Google Analytics(分析)发送网页浏览数据:

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

用于执行发送的对象是上一行代码中安排创建的跟踪器。所发送的数据是存储在该跟踪器上的数据。

本指南介绍向 Google Analytics(分析)发送数据的各种方式,并说明如何控制具体发送哪些数据。

匹配、匹配类型和 Measurement Protocol

我们将跟踪器向 Google Analytics(分析)发送数据称为发送命中,每个命中都必须具有一个命中类型。Google Analytics(分析)代码发送的命中类型为 pageview;其他命中类型包括 screenvieweventtransactionitemsocialexceptiontiming。本指南概要介绍了适用于所有命中类型的概念和方法。您可以在左侧导航栏中的“衡量常见的用户互动”部分找到针对每种命中类型的专题指南。

“命中”是一个 HTTP 请求,其中包含编码成查询字符串并会发送至 Measurement Protocol 的字段/值对。

在加载使用了 analytics.js 的网页时,如果您已打开浏览器的开发者工具,就可以在网络标签中看到发送命中的情况。查找发送至 google-analytics.com/collect 的请求。

发送哪些数据

在向 Measurement Protocol 发送命中时,跟踪器发送当前存储的所有有效 Measurement Protocol 参数字段。例如,跟踪器会发送 titlelocation 等字段,但不会发送 cookieDomainhitCallback 字段。

在某些情况下,您可能需要针对当前命中向 Google Analytics(分析)发送某些字段,但不针对后续命中发送。其中一个例子就是 eventActioneventLabel 字段仅与当前命中相关的某个事件命中。

要仅对当前命中发送某些字段,您可以将这些字段作为参数传递给 send 方法。要对所有后续命中发送字段数据,则应该使用 set 方法来更新跟踪器

send 方法

可以直接使用跟踪器对象本身来调用跟踪器的 send 方法,也可以通过在 ga() 命令队列中添加 send 命令来进行调用。由于大多数情况下您都没有跟踪器对象的引用,因此推荐使用 ga() 命令队列向 Google Analytics(分析)发送跟踪器数据。

使用 ga() 命令队列

用于在 ga() 命令队列中添加 send 命令的签名如下所示:

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

如上所述,通过 hitType...fieldsfieldsObject 参数指定的值仅对当前命中发送。这些值不会存储在跟踪器对象中,也不会对后续命中发送。

如果使用 send 命令传递的任意字段在跟踪器对象上已经设有值,则使用命令中传递的值而不是跟踪器上存储的值。

调用 send 命令时必须指定 hitType,是否需要其他参数取决于所指定的类型。有关更多详情,请参阅左侧导航栏中关于“衡量常见的用户互动”的专题指南。

使用 send 命令的最简单方式是使用 fieldsObject 参数传递所有字段,此方式适用于所有命中类型。例如:

ga('send', {
  hitType: 'event',
  eventCategory: 'Video',
  eventAction: 'play',
  eventLabel: 'cats.mp4'
});

为方便起见,某些命中类型允许直接以参数形式向 send 命令传递常用字段。例如,可将上述用于“event”命中类型的 send 命令改写为:

ga('send', 'event', 'Video', 'play', 'cats.mp4');

要了解针对各种命中类型分别可将哪些字段作为参数传递的完整列表,请参阅 send 方法参考的“参数”部分。

使用指定的跟踪器

如果您要使用指定的跟踪器而不是默认跟踪器,可以在命令字符串中传递跟踪器名称。

以下 send 命令将在名为“myTracker”的跟踪器上调用:

ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');

通过跟踪器对象本身进行调用

如果您拥有对跟踪器对象的引用,就可以直接调用该跟踪器的 send 方法:

ga(function(tracker) {
  tracker.send('event', 'Video', 'play', 'cats.mp4');
});

在命中发送后获得通知

在某些情况下,您需要在匹配已发送到 Google Analytics(分析)时获得通知,这样才能立即采取后续措施。当您需要记录导致用户离开当前页面的特定互动时,这种需要很常见。许多浏览器会在网页开始卸载时立即停止执行 JavaScript,这意味着您用于发送匹配的 analytics.js 命令可能没有机会执行。

例如,您要向 Google Analytics(分析)发送事件以记录用户点击了表单的提交按钮。但在大多数情况下,点击提交按钮会立即开始加载下一页,不会再执行任何 ga('send', ...) 命令。

解决方法是拦截该事件以阻止网页取消加载。然后便可照常向 Google Analytics(分析)发送匹配,发送完成后,可以立即以程序化方式重新提交表单。

hitCallback

要在命中发送完成时收到通知,您需要设置 hitCallback 字段。hitCallback 是一个函数,会在命中发送成功时立即得到调用。

下例介绍了如何取消表单的默认提交操作、向 Google Analytics(分析)发送命中以及使用 hitCallback 函数重新提交该表单:

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: function() {
      form.submit();
    }
  });
});

处理超时情况

以上示例所介绍的方法虽然行之有效,但存在一个严重问题。在 analytics.js 库未加载的情况下(无论什么原因),hitCallback 函数绝不会运行。如果 hitCallback 函数不运行,用户将无法提交表单。

当您在 hitCallback 函数中添加重要的网站功能时,务必使用超时函数来处理 analytics.js 库未能加载的情况。

下例更新了上述代码以使用超时处理。如果在用户点击提交按钮一秒钟之后 hitCallback 还未运行,则立即重新提交该表单。

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Creates a timeout to call `submitForm` after one second.
  setTimeout(submitForm, 1000);

  // Keeps track of whether or not the form has been submitted.
  // This prevents the form from being submitted twice in cases
  // where `hitCallback` fires normally.
  var formSubmitted = false;

  function submitForm() {
    if (!formSubmitted) {
      formSubmitted = true;
      form.submit();
    }
  }

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: submitForm
  });
});

如果您在整个网站中多处使用了上述处理模式,则创建一个实用函数来处理超时更为方便。

以下实用函数接受以一个函数作为输入,并返回一个新函数。如果所返回的函数在超时时限以内(默认的超时时限为一秒)得到调用,该函数将清除超时事件并调用输入的函数。如果所返回的函数在超时时限以内未得到调用,则无条件调用输入函数。

function createFunctionWithTimeout(callback, opt_timeout) {
  var called = false;
  function fn() {
    if (!called) {
      called = true;
      callback();
    }
  }
  setTimeout(fn, opt_timeout || 1000);
  return fn;
}

通过这种方式,您可以使用超时处理轻松封装所有 hitCallback 函数,即使在您的命中发送失败或 analytics.js 库始终无法加载的情况下也可以确保您的网站正常工作。

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: createFunctionWithTimeout(function() {
      form.submit();
    })
  });
});

指定不同的传输机制

默认情况下,analytics.js 会选择 HTTP 方法和传输机制以优化命中的发送。使用这种机制时有三种选项,分别为 'image'(使用 Image 对象)、'xhr'(使用 XMLHttpRequest 对象)或 'beacon'(使用新的 navigator.sendBeacon 方法)。

前两种方法都具有上一部分所描述的问题(在网页未加载的情况下命中往往无法发送)。相比之下,navigator.sendBeacon 方法则是为解决此问题而创建的全新 HTML 功能。

如果您用户的浏览器支持 navigator.sendBeacon,您就可以将 'beacon' 指定为 transport 机制,而无需担心命中回调函数的设置问题。

对于支持此机制的浏览器,以下代码将传输机制设置为 'beacon'

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

// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');

后续步骤

衡量某些类型的用户互动有时需要完成复杂的实现。不过,在许多情况下这些实现已开发完成并作为 analytics.js 插件供您使用。下一篇指南将介绍如何通过 ga() 命令队列使用 analytics.js 插件