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

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

非同步語法的運作方式

_gaq 物件是能夠使用非同步語法的原因。可做為佇列使用,這是「先進先進」的資料結構,在 ga.js 準備好執行呼叫前,持續收集 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 方法,讓您可以透過單一叫用推送多個項目。

返回開頭

正在分割程式碼片段

如果您想將 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 程式碼片段前面。請務必將 UA-XXXX-Y 中的 gaProperty 值換成您網站上使用的屬性。 這和您傳遞至 _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']);

返回開頭