本頁面由 Cloud Translation API 翻譯而成。

ga.js (舊版) 簡介

ga.js 是一個 JavaScript 程式庫，用來評估使用者與網站的互動方式。這是舊版資料庫。如果您是 Google Analytics (分析) 新手，請使用最新追蹤程式庫 analytics.js。

追蹤程式碼快速入門導覽課程

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 物件是允許非同步語法的原因。它是佇列的一種，是先進先出的資料結構，可收集 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 方法，如此一來，即可透過單一叫用推送多個項目。

返回開頭

分割程式碼片段

如果想將 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 日後會長時間設有 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']);

返回開頭