此页面由 Cloud Translation API 翻译。

ga.js（旧版）简介

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

跟踪代码快速入门

Google Analytics（分析）代码段是粘贴到网页中的一小段 JavaScript 代码。它通过将 ga.js 插入网页来激活 Google Analytics（分析）跟踪。要在您的网页上使用此代码，请复制下面的代码段，将 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 对象使异步语法成为可能。它充当一个队列，即先进先出数据结构，直到 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 跟踪代码段现在包含一个窗口属性，您只要将其设置为 true，就可以禁止跟踪代码段向 Google Analytics（分析）发送数据。当 Google Analytics（分析）要设置 Cookie 或将数据发回到 Google Analytics（分析）服务器时，会检查此属性设置是否为 true。如果是，其效果与访问者安装了“停用 Google Analytics（分析）”浏览器插件一样。

要停用跟踪，请将以下窗口属性设为 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']);

返回页首