ga()
指令佇列提供一個介面,您可處理幾乎所有使用 analytics.js 程式庫的操作。
JavaScript 追蹤程式碼片段定義了初始 ga()
指令佇列函式,因此即可在 analytics.js 程式庫完全載入前使用。載入 analytics.js 程式庫後,系統會依照接收順序執行指令佇列中的項目。完成後,系統會立即執行推送至佇列的新指令。
為了盡可能縮短追蹤程式碼片段,ga()
指令佇列已經超載,接受多種不同格式的引數。本文件詳細說明 ga()
指令佇列函式的各種叫用方式。
函式簽章 | |
---|---|
ga(command, [...fields], [fieldsObject]) |
透過以下函式簽章叫用 |
ga(readyCallback) |
藉由將函式傳遞給函式來叫用 由於指令只會在 analytics.js 程式庫完全載入後執行,因此傳送指令佇列的常見原因,是在 analytics.js 程式庫載入完成及準備就緒時做為回呼。 |
新增指令至佇列
透過以下函式簽章叫用 ga()
指令佇列函式時,系統會將指令推送至佇列,以便在程式庫載入後安排執行。
用量
ga(command, [...fields], [fieldsObject])
參數
名稱 | 類型 | 必要 | 說明 | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
command |
string |
是 |
一個 ID,代表要新增至佇列的指令。ID 由三個部分組成 (前兩個是選用項目): [trackerName.][pluginName:]methodName
|
|||||||||
...fields |
* |
否 | 一或多個自選參數,可用於快速指定常用欄位。可使用的欄位數量和具體,取決於呼叫的指令方法。 | |||||||||
fieldsObject |
Object |
否 |
用於指定任何 如果同時在 |
如需個別欄位說明文件,請參閱欄位參考資料。
示例
如要查看個別指令範例,請參閱下方的「指令方法」一節。
已準備好回撥電話
藉由將函式傳遞給函式來叫用 ga()
指令佇列函式,系統會安排在佇列的下一個時間點執行傳遞的函式。
由於指令只會在 analytics.js 程式庫完全載入後執行,因此傳送指令佇列的常見原因,是在 analytics.js 程式庫載入完成及準備就緒時做為回呼。
用量
ga(readyCallback)
參數
名稱 | 類型 | 必要 | 說明 |
---|---|---|---|
readyCallback |
Function |
是 |
當程式庫完全載入並準備好進行互動時,要叫用的回呼函式。此函式是用預設追蹤程式物件叫用,做為第一個引數。如果尚未建立預設追蹤程式,則第一個引數為 注意:叫用回呼函式時,所有
|
示例
// 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');