ga 指令佇列參考資料

ga() 指令佇列提供了一個介面,可用於處理 analytics.js 程式庫的所有用途。

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

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

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

叫用具有下列函式簽章的 ga() 指令佇列函式時,系統會將指令推送到佇列中,並在程式庫載入後排定執行。

ga(readyCallback)

叫用 ga() 指令佇列函式的方式為傳遞函式,將傳遞的函式安排在佇列中的下一個時間點執行。

由於 指令只會在 Analytics (分析) 程式庫完整載入後執行,因此最常見的方法是將函式排入函式佇列的回呼,用於載入 analytics.js 程式庫並已就緒。

將指令加入佇列

叫用具有下列函式簽章的 ga() 指令佇列函式時,系統會將指令推送到佇列中,並在程式庫載入後排定執行。

使用方式

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

參數

名稱 類型 必填 說明
command string

這個 ID 代表要加入佇列的指令。ID 是由三個部分組成 (前兩個部分為選填):

[trackerName.][pluginName:]methodName
trackerName 叫用排程指令的追蹤器名稱。如未指定追蹤器名稱,預設追蹤程式會叫用指令。
pluginName 必要的 analytics.js 外掛程式名稱。如果指定 pluginNamemethodName 必須是外掛程式提供的方法。
methodName 要排定執行的名稱。如果不指定外掛程式名稱,這個方法必須是下列其中一種指令方法
...fields * 用於快速指定常見欄位的一或多個選用便利參數。允許的欄位數量和特定欄位會因呼叫的指令方法而異。
fieldsObject Object

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

如果在 fields 參數和 fieldsObject 中都設定了欄位,系統會使用 fieldsObject 中的值。

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

範例

如需個別指令範例,請參閱下方的指令方法一節。

準備就緒

叫用 ga() 指令佇列函式的方式為傳遞函式,將傳遞的函式安排在佇列中的下一個時間點執行。

由於 指令只會在 Analytics (分析) 程式庫完整載入後執行,因此最常見的方法是將函式排入函式佇列的回呼,用於載入 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 eventCategoryeventActioneventLabeleventValue
social socialNetworksocialActionsocialTarget
timing timingCategorytimingVartimingValuetimingLabel

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

傳回

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');