ga.js(旧版)简介

ga.js 是一个用于衡量用户与您网站的互动情况的 JavaScript 库。这是一个旧版库。如果您刚开始使用 Google Analytics(分析),应该使用最新的跟踪库 analytics.js

跟踪代码快速入门

Google Analytics(分析)代码段是粘贴到网页中的一小段 JavaScript 代码。它通过将 ga.js 插入网页中来启用 Google Analytics(分析)跟踪。要在您的网页上使用此 ID,请复制下面的代码段,并将 UA-XXXXX-X 替换为您的网络媒体资源 ID。将此代码段粘贴到您的网站模板页中,使其显示在 </head> 结束标记之前。

如果除了基本的网页跟踪之外,您还需要跟踪其他 API 提供的方法,请参阅跟踪参考;如需详细了解如何使用异步语法,请参阅使用指南。有关设置跟踪的分步说明,请参阅关于设置跟踪的帮助中心文章。

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

上面的代码段代表异步跟踪网页所需的最低配置。它使用 _setAccount 设置网页的网络媒体资源 ID,然后调用 _trackPageview 将跟踪数据发送回 Google Analytics(分析)服务器。

重要提示:如果您要将网页从传统代码段更新为最新的异步版本,则应先移除现有的跟踪代码段。我们建议不要在同一网页上同时使用这两种代码段。如需了解迁移说明,请参阅迁移到异步

异步语法的运作方式

_gaq 对象使异步语法成为可能。它充当队列,采用先进先出的数据结构,负责收集 API 调用,直到 ga.js 准备好执行这些调用。要向队列中添加内容,请使用 _gaq.push 方法。

要将 API 调用推送到队列,您必须将其从传统 JavaScript 语法转换为命令数组。命令数组只是符合特定格式的 JavaScript 数组。命令数组中的第一个元素是要调用的跟踪器对象方法的名称。此值必须是一个字符串。其余元素是要传递给跟踪器对象方法的参数。这些值可以是任何 JavaScript 值。

以下代码使用传统语法调用 _trackPageview()

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

异步语法中的等效代码需要对 _gaq.push 进行两次调用。

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

在异步语法中,包含了跟踪器对象的创建,但我们仍需通过某种方法来设置跟踪器的网络媒体资源 ID。添加了 _setAccount 方法以提供此功能。在异步跟踪和传统跟踪中,所有其他跟踪器对象方法都是相同的。只是语法不同。

如需详细了解异步语法,请参阅跟踪参考,了解 _gaq.push 方法。

返回页首

使用 HTML 事件处理脚本进行跟踪

在 DOM 事件处理脚本中也应使用异步跟踪语法。例如,点击以下按钮时会生成一个事件。

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

即使在浏览器完成 ga.js 加载之前点击此按钮,系统也会捕获并最终执行该事件。使用传统跟踪时,浏览器可能会在这种情况下抛出异常。

返回页首

将函数推送到队列

除了命令数组之外,您还可以将函数对象推送到 _gaq 队列。这些函数可以包含任意 JavaScript,并且与命令数组一样,它们也会按推送到 _gaq 的顺序执行。此方法有助于调用返回值的跟踪 API。例如,以下代码会构建链接器网址,并为包含结果的链接设置 href 属性。

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

上例使用 _gat 创建了一个跟踪器对象,但由于对象被赋予了局部变量,所以函数之外的代码不能使用该对象。虽然这是可以接受的,但您可以使用 _gat._createTracker 方法创建一个可全局访问的永久对象。 以下代码演示了如何使用该方法。

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

上面的示例在函数内创建了一个异步跟踪器,稍后在命令数组中按名称引用了该跟踪器。

反之亦然。例如,如果您需要使用通过之前推送的命令数组创建的异步跟踪器对象,请使用 _gat._getTrackerByName 方法。以下代码演示了它的工作原理。

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

返回页首

一次推送,多个命令

您可以一次推送所有命令,而无需为每个调用输入 _gaq.push(...)。以下代码演示了这种方法。

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

这是因为 _gaq.push 方法模仿了 Array.push 方法,后者允许通过一次调用推送多个项。

返回页首

拆分代码段

如果您希望将 Google Analytics(分析)代码段放在网页底部,您应当了解并不需要将整个代码段都放在底部。您仍然可以将代码段分成两半,保留异步加载的大部分优势,即将前半部分置于页面顶部,而将其余部分移至底部。由于跟踪代码段的第一部分对网页呈现影响很小甚至没有影响,因此您可以将这部分留在顶部,而将用于插入 ga.js 的那部分代码段放在底部。

使用一分为二的异步代码段的网页可能如下所示:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

两段代码都需要封装在各自的脚本标记中,但只有原始异步代码段的最后六行需要移至底部。用于将方法推送到 _gaq 的所有代码行都可以留在顶部。

返回页首

避免常见问题

使用异步语法或传统语法时,请注意以下几点:

  • 方法名称区分大小写
    如果您使用的方法名称大小写不正确,方法调用将不起作用。示例:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • 使用正确的方法名称
    如果跟踪没有正常运行,请检查并确保您使用的方法名称正确无误。示例:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • 只有字符串才应在传递时加引号。所有其他类型都不应加引号。
    任何非字符串值(例如布尔值、对象字面量、函数或数组)在传递时不应加引号。只有在传递要解释为字符串的内容时,才应使用引号。如果您正在从传统语法迁移到异步语法,那么在传统语法中不加引号传递的任何函数参数在异步语法中仍然不加引号。示例:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • 确保字符串开头或结尾处没有任何空格。
    示例:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

返回页首

停用跟踪功能

在某些情况下,可能需要在不移除代码段的情况下停用网页上的 Google Analytics(分析)跟踪代码。例如,如果网站上的隐私权政策允许访问者选择停用 Google Analytics(分析)跟踪,您可能就需要这样做。

ga.js 跟踪代码段现在包含一个 window 属性,您只要将其设置为 true,就可以禁止跟踪代码段向 Google Analytics(分析)发送数据。 当 Google Analytics(分析)要设置 Cookie 或将数据发回到 Google Analytics(分析)服务器时,会检查此属性是否设为 true。如果是,其效果相当于访问者 安装了“停用 Google Analytics(分析)”浏览器插件

要停用跟踪,请将以下 window 属性设置为 true:

window['ga-disable-UA-XXXXXX-Y'] = true;

其中,值 UA-XXXXXX-Y 对应于您要停用跟踪的网络媒体资源的 ID。

此窗口属性必须在调用跟踪代码之前设置。您必须在要停用 Google Analytics(分析)跟踪的每个页面上设置此属性。如果该属性未设置或设为 false,则跟踪功能会正常工作。

例如,如果网页上的 Google Analytics(分析)跟踪代码包含:

_gaq.push['_setAccount', 'UA-123456-1']

并且您想禁止该跟踪代码设置 Cookie 或将数据发送回 Google Analytics(分析),请在调用跟踪代码之前使用以下代码:

window['ga-disable-UA-123456-1'] = true;

如果您在具有多个网络媒体资源 ID 的网页上使用多个跟踪器,则必须将每个网络媒体资源的等效 window['ga-disable-UA-XXXXXX-Y'] 变量设置为 true,才能完全停用该网页上的 Google Analytics(分析)跟踪。

示例

下面是一个简单的代码示例,可用于为用户提供选择停用功能。

首先,添加新的 HTML 链接到您的网站以执行选择停用逻辑:

<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>

然后在 ga.js 代码段前面添加以下代码段。请务必将 gaProperty 的值从 UA-XXXX-Y 替换为您网站上所用的属性。 这个值应与您传递给 _setAccount 命令的值相同。

<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';

// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
  window[disableStr] = true;
}

// Opt-out function
function gaOptout() {
  document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
  window[disableStr] = true;
}
</script>

当用户点击选择停用 HTML 链接时,自定义的 gaOptout 函数会执行。它会设置未来很长一段时间内的 Cookie,并停用 analytics.js 数据收集。 当用户回访此网站时,上述脚本将检查是否已设置选择停用 Cookie。如果包含,则 analytics.js 数据收集也会停用。

强制采用 SSL (HTTPS)

要强制 Google Analytics(分析)始终使用 SSL 发送数据(即使是从不安全的网页 (HTTP) 发送数据),请使用 _gat._forceSSL 方法,如下例所示:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

返回页首