ga 指令佇列參考資料

ga() 指令佇列提供一個介面，您可處理幾乎所有使用 analytics.js 程式庫的操作。

JavaScript 追蹤程式碼片段定義了初始 ga() 指令佇列函式，因此即可在 analytics.js 程式庫完全載入前使用。載入 analytics.js 程式庫後，系統會依照接收順序執行指令佇列中的項目。完成後，系統會立即執行推送至佇列的新指令。

為了盡可能縮短追蹤程式碼片段，ga() 指令佇列已經超載，接受多種不同格式的引數。本文件詳細說明 ga() 指令佇列函式的各種叫用方式。

函式簽章
ga(command, [...fields], [fieldsObject])

透過以下函式簽章叫用 ga() 指令佇列函式時，系統會將指令推送至佇列，以便在程式庫載入後安排執行。
ga(readyCallback)

藉由將函式傳遞給函式來叫用 ga() 指令佇列函式，系統會安排在佇列的下一個時間點執行傳遞的函式。

由於指令只會在 analytics.js 程式庫完全載入後執行，因此傳送指令佇列的常見原因，是在 analytics.js 程式庫載入完成及準備就緒時做為回呼。

新增指令至佇列

透過以下函式簽章叫用 ga() 指令佇列函式時，系統會將指令推送至佇列，以便在程式庫載入後安排執行。

使用方式

ga(command, [...fields], [fieldsObject])

參數

名稱 類型 必要 說明
command string 是

一個 ID，代表要新增至佇列的指令。ID 由三個部分組成 (前兩個是選用項目)：

[trackerName.][pluginName:]methodName
trackerName 叫用排程指令的追蹤器名稱。如未指定追蹤器名稱，則會在預設追蹤器上叫用指令。
pluginName 所需的 analytics.js 外掛程式名稱。如果指定 pluginName，則 methodName 必須是外掛程式提供的方法。
methodName 要排定執行排程的方法名稱。當未指定外掛程式名稱時，這個方法必須是下列其中一種指令方法。
...fields * 否 一或多個自選參數，可用於快速指定常用欄位。可使用的欄位數量和具體，取決於呼叫的指令方法。
fieldsObject Object 否

用於指定任何 fields 參數中未指定其餘值的物件。

如果同時在 fields 參數和 fieldsObject 中設定欄位，系統會使用 fieldsObject 中的值。

如需個別欄位說明文件，請參閱欄位參考資料。

示例

如要查看個別指令範例，請參閱下方的「指令方法」一節。

已準備好回撥電話

藉由將函式傳遞給函式來叫用 ga() 指令佇列函式，系統會安排在佇列的下一個時間點執行傳遞的函式。

由於指令只會在 analytics.js 程式庫完全載入後執行，因此傳送指令佇列的常見原因，是在 analytics.js 程式庫載入完成及準備就緒時做為回呼。

使用方式

ga(readyCallback)

參數

名稱 類型 必要 說明
readyCallback Function 是

當程式庫完全載入並準備好進行互動時，要叫用的回呼函式。此函式是用預設追蹤程式物件叫用，做為第一個引數。如果尚未建立預設追蹤程式，則第一個引數為 undefined。

注意：叫用回呼函式時，所有 ga 物件方法均可使用。

示例

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});

// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

指令方法詳細資料

以下列出可傳送至 ga() 指令佇列的所有方法 (不含外掛程式方法)。

create

以指定欄位建立新的追蹤器執行個體。

使用方式

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

參數

如需個別欄位說明文件，請參閱欄位參考資料。

傳回

undefined

示例

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');

// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

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

使用方式

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

傳送的欄位是 ...fields 參數和 fieldsObject 中指定的值，並與目前儲存在追蹤器上的欄位合併。

參數

可由 ...fields 參數指定的欄位會因命中類型而異。下表列出與各命中類型對應的欄位。未列出的命中類型不接受 ...fields 參數，僅支援 fieldsObject。

命中類型 ...fields
pageview page
event eventCategory、eventAction、eventLabel、eventValue
social socialNetwork、socialAction、socialTarget
timing timingCategory、timingVar、timingValue、timingLabel

如需個別欄位說明文件，請參閱欄位參考資料。

傳回

undefined

示例

// Sends a pageview hit.
ga('send', 'pageview');

// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

在追蹤器物件上設定單一欄位和值組合，或一組欄位/值組合。

使用方式

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);

// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

參數

如需個別欄位說明文件，請參閱欄位參考資料。

傳回

undefined

示例

// Sets the page field to "/about.html".
ga('set', 'page', '/about.html');

// Sets the page field to "/about.html" and the title to "About".
ga('set', {
  page: '/about.html',
  title: 'About'
});

require

需要 analytics.js 外掛程式。

使用方式

ga('[trackerName.]require', pluginName, [pluginOptions]);

參數

名稱 類型 必要 說明
pluginName string 是 所需外掛程式的名稱。注意：如果外掛程式不是官方 analytics.js 外掛程式，就必須在網頁上其他位置提供。
pluginOptions Object 否 會在執行個體化時傳遞至外掛程式建構函式的初始化物件。

傳回

undefined

範例

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');

// Requires the Advertising Features plugin
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

提供 analytics.js 外掛程式及其方法，以便與 ga() 指令佇列搭配使用。

ga('provide', pluginName, pluginConstuctor);

參數

名稱 類型 必要 說明
pluginName string 是 提供的外掛程式名稱。這個名稱必須與所有 require 呼叫時使用的名稱相同。
pluginConstuctor Function 是 的建構函式函式可提供所有外掛程式邏輯和方法。系統會使用 require 方法中指定的 pluginsOptions 物件叫用此建構函式。

範例

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

移除追蹤器物件。

使用方式

ga('[trackerName.]remove');

示例

// Remove the default tracker.
ga('remove');

// Remove the  tracker named "myTracker".
ga('myTracker.remove');