將資料傳送至 Google Analytics (分析)

JavaScript 評估程式碼片段的最後一行會在 ga() 指令佇列中加入 send 指令,將網頁瀏覽傳送給 Google Analytics (分析):

ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

執行傳送作業的物件是指已在前一行程式碼中安排建立的追蹤器,而傳送的資料是儲存在該追蹤器中的資料。

本指南將說明傳送資料至 Google Analytics (分析) 的各種方法,並說明如何控管要傳送哪些資料。

命中、命中類型和 Measurement Protocol

追蹤器將資料傳送至 Google Analytics (分析) 時,系統會呼叫一次命中,而每次命中都必須設定一個命中類型。Google Analytics (分析) 代碼會傳送 pageview 類型的命中;其他命中類型包括 screenvieweventtransactionitemsocialexceptiontiming。本指南將概略說明所有命中類型通用的概念和方法。您可以在左側導覽面板的「評估常見的使用者互動」一節下方,找到各命中類型的個別指南。

命中是 HTTP 要求,由編碼成查詢字串的欄位和值組合組成,並傳送至 Measurement Protocol

當您載入使用 analytics.js 的網頁時,如果瀏覽器的開發人員工具已開啟,則可在「網路」分頁中看到已傳送的命中。查看傳送到 google-analytics.com/collect 的要求。

系統會傳送哪些資料

將命中資料傳送至 Measurement Protocol 時,追蹤程式會傳送目前儲存的所有欄位,且這些是有效的 Measurement Protocol 參數。舉例來說,系統會傳送 titlelocation 等欄位,但不會傳送 cookieDomainhitCallback

在某些情況下,您可能想要將目前命中的欄位傳送給 Google Analytics (分析),但不要傳送任何後續命中的欄位。以事件命中為例,其中 eventActioneventLabel 欄位只與目前命中相關。

如果只要傳送含有目前命中的欄位,可以將這些欄位做為引數傳遞至 send 方法。若要與所有後續命中一併傳送欄位資料,請使用 set 方法更新追蹤程式

傳送方法

您可以直接在追蹤程式物件本身呼叫追蹤器的 send 方法,或是將 send 指令新增至 ga() 指令佇列。由於您多數時候並沒有追蹤工具物件的參照,因此建議您使用 ga() 指令佇列,將追蹤程式資料傳送至 Google Analytics (分析)。

使用 ga() 指令佇列

send 指令新增至 ga() 指令佇列的簽名如下所示:

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

如上所述,系統只會針對目前的命中傳送 hitType...fieldsfieldsObject 參數中指定的值。這些呼叫不會儲存在追蹤器物件上,也不會與後續命中一併傳送。

如果追蹤器物件已設有透過 send 指令傳遞的任何欄位,系統會使用指令傳送的值,而非儲存在追蹤器上的值。

呼叫 send 指令必須指定 hitType,並視指定的類型而定,可能需要使用其他參數。詳情請參閱左側導覽面板中的評估常見使用者互動指南。

如要使用 send 指令,最簡單的做法就是使用 fieldsObject 參數傳遞所有欄位,而且適用於所有命中類型。例如:

ga('send', {
  hitType: 'event',
  eventCategory: 'Video',
  eventAction: 'play',
  eventLabel: 'cats.mp4'
});

為了方便起見,特定命中類型可將常用欄位直接做為引數傳遞至 send 指令。舉例來說,上述「事件」命中類型的 send 指令可改寫為:

ga('send', 'event', 'Video', 'play', 'cats.mp4');

如需各種命中類型可傳送哪些欄位的完整清單,請參閱傳送方式參考資料的「參數」一節。

使用已命名的追蹤器

如果您使用已命名的追蹤器而非預設的追蹤程式,可以在指令字串中傳送其名稱。

系統會在名為「myTracker」的追蹤器上呼叫以下 send 指令:

ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');

在追蹤器物件上

如果您有對追蹤器物件的參照,可以直接呼叫該追蹤器的 send 方法:

ga(function(tracker) {
  tracker.send('event', 'Video', 'play', 'cats.mp4');
});

知道命中的傳送時間

在某些情況下,您必須知道命中資料傳送至 Google Analytics (分析),才能在收到後立即採取行動。在需要記錄會讓使用者離開目前頁面的特定互動時,這種狀況就很常見。許多瀏覽器會在網頁開始卸載後立即停止執行 JavaScript,這表示用於傳送命中的 analytics.js 指令可能永遠不會執行。

舉例來說,假設您想將事件傳送至 Google Analytics (分析),以記錄使用者點擊表單提交按鈕的使用者,就屬於這種情況。在多數情況下,點選「提交」按鈕會立即開始載入下一頁,而且也不會執行任何 ga('send', ...) 指令。

解決方法是攔截事件,停止載入網頁。接下來,您可以如往常一樣將命中資料傳送至 Google Analytics (分析),並在收到命中資料後,透過程式輔助方式重新提交表單。

hitCallback

如要在命中送出時收到通知,請設定 hitCallback 欄位。hitCallback 是在命中成功傳送後立即呼叫的函式。

以下範例說明如何取消表單的預設提交動作、傳送命中給 Google Analytics (分析),然後使用 hitCallback 函式重新提交表單:

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: function() {
      form.submit();
    }
  });
});

處理逾時

上述範例成效良好,但有一個嚴重問題。如果因任何原因而無法載入 analytics.js 程式庫,hitCallback 函式將一律無法執行。如果 hitCallback 函式從未執行,使用者就無法提交表單。

每次將重要網站功能放入 hitCallback 函式時,您「一律」應該使用逾時函式來處理 analytics.js 程式庫無法載入的情況。

下一個範例會更新上述程式碼,改用逾時。如果使用者在點選「提交」按鈕後經過一秒,且 hitCallback 尚未執行,則仍要重新提交表單。

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Creates a timeout to call `submitForm` after one second.
  setTimeout(submitForm, 1000);

  // Keeps track of whether or not the form has been submitted.
  // This prevents the form from being submitted twice in cases
  // where `hitCallback` fires normally.
  var formSubmitted = false;

  function submitForm() {
    if (!formSubmitted) {
      formSubmitted = true;
      form.submit();
    }
  }

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: submitForm
  });
});

如果您在網站的許多地方都採用上述模式,建議您建立公用程式函式來處理逾時。

以下公用程式函式會接受函式做為輸入內容,並傳回新的函式。如果在逾時時間之前呼叫傳回的函式 (預設逾時為一秒),系統會清除逾時並叫用輸入函式。如未在逾時期限前呼叫傳回的函式,系統一律會呼叫輸入函式。

function createFunctionWithTimeout(callback, opt_timeout) {
  var called = false;
  function fn() {
    if (!called) {
      called = true;
      callback();
    }
  }
  setTimeout(fn, opt_timeout || 1000);
  return fn;
}

現在,您可以輕鬆地將所有 hitCallback 函式納入逾時值,這樣即使命中未傳送或未載入 analytics.js 程式庫,網站也能正常運作。

// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');

// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {

  // Prevents the browser from submitting the form
  // and thus unloading the current page.
  event.preventDefault();

  // Sends the event to Google Analytics and
  // resubmits the form once the hit is done.
  ga('send', 'event', 'Signup Form', 'submit', {
    hitCallback: createFunctionWithTimeout(function() {
      form.submit();
    })
  });
});

指定不同的傳輸機制

根據預設,analytics.js 會挑選 HTTP 方法和傳輸機制,以便以最佳方式傳送命中資料。三個選項是 'image' (使用 Image 物件)、'xhr' (使用 XMLHttpRequest 物件),或 'beacon' (使用新的 navigator.sendBeacon 方法)。

這兩種方法共用上一節所述的問題 (如果網頁卸載,通常就不會傳送命中)。相較之下,navigator.sendBeacon 方法是一種新的 HTML 功能,可解決這個問題。

如果使用者的瀏覽器支援 navigator.sendBeacon,您可以將 'beacon' 指定為 transport 機制,而不必設定命中回呼。

下列程式碼會在支援的瀏覽器中,將傳輸機制設為 'beacon'

ga('create', 'UA-XXXXX-Y', 'auto');

// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');

後續步驟

評估特定類型的使用者互動有時可能需要進行複雜的導入作業。不過,在許多情況下,這些導入做法都已經過開發,可做為 analytics.js 外掛程式使用。下一份指南將說明如何透過 ga() 指令佇列使用 analytics.js 外掛程式