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

ga.js 簡介 (舊版)

ga.js 是 JavaScript 程式庫，可用於評估使用者與網站的互動情形。這是舊版程式庫。如果您是開始使用 Google Analytics (分析)，建議您採用最新的追蹤程式庫 analytics.js。

追蹤程式碼快速入門

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 (分析) 伺服器。

重要注意事項：如果您將網頁從傳統程式碼片段更新為最新的非同步版本，請先移除現有的追蹤程式碼片段。我們不建議在相同網頁上同時使用這兩種程式碼片段。如需遷移操作說明，請參閱遷移至 Async。

非同步語法的運作方式

您可以透過 _gaq 物件設定非同步語法。它會充當佇列，這是「先進先出」的資料結構，用來收集 API 呼叫，直到 ga.js 準備好執行呼叫為止。如要將內容加入佇列，請使用 _gaq.push 方法。

如要將 API 呼叫推送至佇列，您必須將 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 (分析) 不透露資訊瀏覽器外掛程式。

如要停用追蹤功能，請將下列 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']);

返回開頭