ga()
指令佇列提供了一個介面,可用於處理 analytics.js 程式庫的所有用途。
JavaScript 追蹤程式碼片段定義了初始的ga()
指令佇列函式,因此即使在 analytics.js 程式庫完全載入之前,也可以使用這項函式。載入 analytics.js 程式庫後,指令佇列中的項目會依接收順序執行。完成後,系統會立即執行推送至佇列的新指令。
為了盡可能縮減追蹤程式碼片段,ga()
指令佇列會超載,以接受多種不同格式的引數。本文件詳細說明 ga()
指令佇列函式的各種叫用方式。
函式簽章 | |
---|---|
ga(command, [...fields], [fieldsObject]) |
叫用具有下列函式簽章的 |
ga(readyCallback) |
叫用 由於 指令只會在 Analytics (分析) 程式庫完整載入後執行,因此最常見的方法是將函式排入函式佇列的回呼,用於載入 analytics.js 程式庫並已就緒。 |
將指令加入佇列
叫用具有下列函式簽章的 ga()
指令佇列函式時,系統會將指令推送到佇列中,並在程式庫載入後排定執行。
使用方式
ga(command, [...fields], [fieldsObject])
參數
名稱 | 類型 | 必填 | 說明 | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
command |
string |
是 |
這個 ID 代表要加入佇列的指令。ID 是由三個部分組成 (前兩個部分為選填): [trackerName.][pluginName:]methodName
|
|||||||||
...fields |
* |
否 | 用於快速指定常見欄位的一或多個選用便利參數。允許的欄位數量和特定欄位會因呼叫的指令方法而異。 | |||||||||
fieldsObject |
Object |
否 |
用於指定任何 如果在 |
如需個別欄位說明文件,請參閱欄位參考資料。
範例
如需個別指令範例,請參閱下方的指令方法一節。
準備就緒
叫用 ga()
指令佇列函式的方式為傳遞函式,將傳遞的函式安排在佇列中的下一個時間點執行。
由於 指令只會在 Analytics (分析) 程式庫完整載入後執行,因此最常見的方法是將函式排入函式佇列的回呼,用於載入 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');