傳送資料至 Google Analytics (分析)

JavaScript 評估程式碼片段的最後一行會在 ga() 指令佇列中加入 send 指令,以便將 pageview 傳送至 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
  });
});

如果您在網站的許多位置使用上述模式,建立公用程式函式來處理逾時可能會比較簡單。

下列公用程式函式接受函式做為輸入,並傳回新的函式。如果在逾時期限前呼叫傳回的函式 (預設逾時時間為 1 秒),就會清除逾時並叫用輸入函式。如果在逾時期限前沒有呼叫傳回的函式,則無論呼叫哪個函式,都會呼叫輸入函式。

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 物件),或使用新 navigator.sendBeacon 方法的 'beacon'

這兩種方法都會分享上一節所述的問題 (當網頁卸載時,通常就不會傳送命中)。相較之下,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 外掛程式