此页面由 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 准备好执行 API 调用之前收集 API 调用。如需向队列中添加内容，请使用 _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']);

返回页首