通过 gtag.js 向 Google Analytics(分析)发送数据

本指南介绍如何使用 gtag.js 将数据从您的网站发送到 Google Analytics(分析)。

event 命令发送数据

您的网站上添加全局代码段后,使用 event 命令将数据发送到 Google Analytics(分析)。例如,要在 Google Analytics(分析)中记录用户登录事件,请使用以下 event 命令:

gtag('event', 'login');

event 命令具有以下语法:

gtag('event', 'event_name', {
  // Event parameters
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

有关 event 命令的详细说明,请参阅发送事件。有关 Google Analytics(分析)事件参数的详细说明,请参阅事件参数

指定接收数据的组和媒体资源

向 Google Analytics(分析)发送数据时,您可以指定接收数据的组和/或媒体资源。一个组包含一个或多个媒体资源。

定义组

在将数据发送到组之前,您必须先定义组和相关的媒体资源跟踪 ID。

定义 default

以下为包含一个或多个 Google Analytics(分析)媒体资源的 default 组的定义:

gtag('config', 'GA_TRACKING_ID');

相当于以下代码:

gtag('config', 'GA_TRACKING_ID', {'groups': 'default'});

例如,以下代码定义了包含两个 Google Analytics(分析)媒体资源的 default 组:

gtag('config', 'GA_TRACKING_ID_1');
gtag('config', 'GA_TRACKING_ID_2');

相当于以下代码:

gtag('config', 'GA_TRACKING_ID_1', {'groups': 'default'});
gtag('config', 'GA_TRACKING_ID_2', {'groups': 'default'});

当定义 default 组时,gtag.js 会向组中的媒体资源自动发送网页浏览事件。

定义非默认组

以下为包含一个或多个 Google Analytics(分析)媒体资源的非默认组的定义:

gtag('config', 'GA_TRACKING_ID', {'groups': 'group_name'});

例如,以下代码定义了包含两个 Google Analytics(分析)媒体资源的 access 组:

gtag('config', 'GA_TRACKING_ID_1', {'groups': 'access'});
gtag('config', 'GA_TRACKING_ID_2', {'groups': 'access'});

当定义非默认组时,gtag.js 会向组中的媒体资源自动发送网页浏览事件。

将数据发送到默认组

要将数据发送到 default 组,请使用以下 event 命令:

gtag('event', 'event_name', {
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

例如:

gtag('event', 'sign_up', {'method': 'Google'});

将数据发送到非默认组

要将数据发送到非默认组,请提供组名称作为 send_to 参数的值:

gtag('event', 'event_name', {
  'send_to': 'group_name',
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

例如:

gtag('event', 'sign_up', {
  'send_to': 'access',
  'method': 'Google'
});

将数据发送到多个组

要将数据发送到属于两个或更多组的 Google Analytics(分析)媒体资源,请提供组名称作为 send_to 参数的值:

gtag('event', 'event_name', {
  'send_to': ['group_name_1', 'group_name_2', ... ],
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

例如:

gtag('event', 'sign_up', {
  'send_to': ['default', 'group_1', 'group_2'],
  'method': 'Google'
});

向特定媒体资源发送数据

要将数据发送到特定的 Google Analytics(分析)媒体资源,请提供媒体资源跟踪 ID 作为 send_to 参数的值:

gtag('event', 'event_name', {
  'send_to': ['GA_TRACKING_ID_1', 'GA_TRACKING_ID_2', ...],
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

例如:

gtag('event', 'sign_up', {
  'send_to': ['GA_TRACKING_ID_1', 'GA_TRACKING_ID_2'],
  'method': 'Google'
});

将数据发送到特定的组和媒体资源

要将数据发送到特定组和媒体资源,请提供组名和媒体资源跟踪 ID 作为 send_to 参数的值:

gtag('event', 'event_name', {
  'send_to': ['group_name_1', 'group_name_2', ..., 'GA_TRACKING_ID_1', 'GA_TRACKING_ID_2', ...],
  'parameter_1': 'value_1',
  'parameter_2': 'value_2',
  // ...
});

例如:

gtag('event', 'sign_up', {
  'send_to': ['default', 'group_1', 'GA_TRACKING_ID_1', 'GA_TRACKING_ID_2'],
  'method': 'Google'
});

了解事件发送的时间

在某些情况下,您需要知道事件何时成功发送至 Google Analytics(分析),以便您随后立即采取措施。这种情形常见于当您需要记录导致用户离开当前页面的特定互动时。许多浏览器一旦页面开始卸载就停止执行 JavaScript,这意味着发送事件的 gtag.js 命令可能永远不会执行。

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

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

实现事件回调函数

要在事件发送完成时收到通知,可以实现一个事件回调函数,一旦事件成功发送系统就会调用该函数。

以下示例说明如何取消表单的默认提交操作、向 Google Analytics(分析)发送事件以及使用事件回调函数重新提交该表单:

// 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.
  gtag('event', 'signup_form_complete', {
    'event_callback': function() {
      form.submit();
    }
  });
});

处理超时

以上示例所介绍的方法虽然行之有效,但存在一个严重问题。如果(无论什么原因)gtag.js 库未能加载,事件回调函数将永远不会运行,用户将永远无法提交表单。

当您在事件回调函数中添加重要的网站功能时,务必使用超时函数来处理 gtag.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();

  // 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 the event callback function 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.
  gtag('event', 'signup_form_complete', { 'event_callback': {
    submitForm();
  }});
});

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

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

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

通过这种方式,您可以使用超时处理封装所有事件回调函数,即使在您的事件发送失败或 gtag.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.
  gtag('event', 'signup_form', { 'event_callback': {
    createFunctionWithTimeout(function() {
      form.submit();
    })
  }});
});

指定不同的传输机制

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

前两种方法都具有上一节所描述的问题(如果遇到网页卸载的情况匹配往往无法发送)。相比之下,navigator.sendBeacon 方法则是为解决此问题而创建的全新 HTML 功能。

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

以下代码在支持此功能的浏览器中将传输机制设置为 'beacon'

gtag('config', 'GA_TRACKING_ID', { 'transport_type': 'beacon'});

后续步骤

了解页面跟踪和其他事件跟踪