方法参考 - 网络跟踪 (analytics.js)

analytics.js 库提供了两种主要对象来与 Google Analytics(分析)互动。每种对象都包含多种方法:

ga 对象的方法

在页面上添加默认的 analytics.js JavaScript 代码段后,它会创建名为 ga 的全局对象。开发者可使用 ga 对象创建跟踪器对象,进而发送数据给 Google Analytics(分析)网络媒体资源。

create

创建新的默认跟踪器对象。

ga('create', trackingId, opt_configObject);

参数

  • String trackingId – 所要跟踪的网站的网络媒体资源 ID。
  • Object opt_configObject – 包含配置字段/值对的可选对象。

示例

创建默认跟踪器。

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

使用自定义 Cookie 名称创建跟踪器。

ga('create', 'UA-XXXX-Y', 'auto', {'cookieName': '_ga2'});

使用同步语法创建跟踪器:

var tracker = ga.create('UA-XXXX-Y', 'auto');

ga('create', ...) 可接受 trackingIdcookieDomainname 字段的位置参数和对象参数。顺序很重要。例如,以下两个代码段是相同的:

ga('create', 'UA-XXXX-Y', 'auto', 'T1000');
ga('create', {trackingId: 'UA-XXXX-Y', cookieDomain: 'auto', name: 'T1000'});

getByName

返回具有指定名称的跟踪器对象,如果当前不存在使用指定名称的跟踪器对象,则返回 null。

ga.getByName(name);

参数

  • String name – 要获取的跟踪器的名称。

返回值

  • Tracker – 跟踪器对象。

示例

返回名为shoehorn的跟踪器对象:

ga(function() {
  var tracker = ga.getByName('shoehorn');
});

getAll

返回包含当前所有跟踪器对象的数组,对象按其创建时间排序:

ga.getAll();

返回值

  • Array<Tracker> – 包含所有跟踪器对象的数组。

示例

返回所有跟踪器对象并提醒对象名称:

ga(function() {
  var trackers = ga.getAll();

  for (var i=0; i < trackers.length; ++i) {
    var tracker = trackers[i];
    alert(tracker.get('name'));
  }
});

跟踪器对象的方法

在使用 create 方法创建跟踪器对象后,您可使用以下方法来与 Google Analytics(分析)互动。

send

向 Google 的数据收集服务器发送跟踪信标。通过可选字段对象,用户可以仅为当前匹配覆盖一个或多个字段值。

ga('send', hitType, opt_fieldObject);

参数

  • String hitType – 要发送的匹配类型。支持的值包括:
  • Object opt_fieldObject – 一个包含一个或多个字段/值对的对象,用于仅为当前匹配覆盖字段值。在匹配完成后,各字段将恢复为原始值。

示例

发送网页浏览类型的匹配,覆盖网页标题。

ga('send', 'pageview', {'title': 'my new title'});

set

更新当前与指定字段关联的值。您可使用单个字段和值来调用 set 方法:

ga('set', fieldName, value);

参数

  • String fieldName – 要设置的字段的名称。
  • String|Number|Object|Boolean value – 要关联至指定字段的新值。

您还可以使用包含多个字段/值对的对象来调用 set,进行批量更新。

ga('set', fieldObject);

在跟踪器对象的生命周期内,设置的值将在所有后续的 send 调用中保持不变。

参数

  • Object fieldObject – 包含一个或多个要设置的字段/值对的对象。

示例

为所有后续的匹配设置 page 字段:

ga('set', 'page', '/my-new-page');

为所有后续的匹配同时设置 pagetitle

ga('set', {
  'page': '/my-new-page',
  'title': 'my new title'
});

get

返回当前与指定字段关联的值,应在实例化的跟踪器对象上调用。

var fieldValue = tracker.get(fieldName);

参数

  • String fieldName – 要获取的字段的名称。

返回值

  • String|Number|Object – 字段的值。

示例

获取跟踪器的当前页面:

ga(function(tracker) {
  var page = tracker.get('page');
});

此函数仅在 analytics.js 库加载后执行。当函数执行时,tracker 参数将引用默认跟踪器(假设跟踪器是在函数调用前创建)。随后,系统将使用跟踪器引用获取 page 值。

调用语法

您可通过多种方法来调用每个 ga 方法。

异步(默认跟踪器)

anaytics.js JavaScript 代码段会通过异步方式加载,避免浏览器为了加载库而暂停。因此,您不需要在库加载前后同步代码,而是可以将方法名称作为首个参数进行传递,像使用函数那样使用 ga 对象:

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

这会在库完成加载后马上执行。create 方法将创建名为 t0 的默认跟踪对象。随后,系统将在默认跟踪对象上执行 send 方法或使用此语法调用的任何其他方法。

在这种情况下,创建默认跟踪器对象是为了方便大部分实现的进行。

异步(已命名的跟踪器)

在某些情况下,您可能想在同一个页面上创建多个跟踪器。为区分各个跟踪器,您必须为每个额外跟踪器指定名称。

您可使用 create 方法的可选配置对象参数设置 name 配置字段,以创建已命名跟踪器对象。

ga('create', 'UA-XXXX-Y', 'auto', {'name': 'tracker2'});

然后,您可以在方法前面添加跟踪器名称和一个“.”(点号),在已命名跟踪器上调用跟踪器方法:

ga('tracker2.send', 'pageview');

同步

anaytics.js 库还支持以同步方式调用方法。在这种情况下,您可以分别直接在 gatracker 对象上调用方法:

var tracker = ga.create('UA-XXXX-Y', 'auto');
tracker.send('pageview');

异步性同步

在一些情况下,您只能在库加载后调用某些方法。例如,get 方法只在库已加载、跟踪器已创建且字段已设置的情况下方可工作。为满足这种要求,您可以向 ga 对象传递只在库加载后执行的函数:

ga(function(tracker) {
  var page = tracker.get('name');
});

您传递给 ga 对象的函数会接受某个在执行后可生成默认跟踪器值的参数。然后,您就可以搭配同步语法来使用跟踪器对象。例如,以下代码也可工作:

ga('create', 'UA-XXXX-Y', 'auto');
ga(function(tracker) {
  tracker.send('pageview');
});

同样,要跟踪创建的所有跟踪器上的网页浏览,您可以使用:

ga(function() {
  var trackers = ga.getAll();
  for (var i=0; i<trackers.length; ++i) {
    var tracker = trackers[i];
    tracker.send('pageview');
  }
});

如果您想开发附加信息,但不知道网站上创建了多少跟踪器,这种语法会特别有用。利用这种语法,函数可在跟踪代码加载后为页面上的每个跟踪器执行许多额外的逻辑。