Tham chiếu hàng đợi lệnh ga

Hàng đợi lệnh ga() cung cấp giao diện để thực hiện hầu hết mọi việc bạn cần làm với thư viện analytics.js.

Đoạn mã theo dõi JavaScript xác định hàm hàng đợi lệnh ga() ban đầu, vì vậy, bạn có thể sử dụng đoạn mã này ngay cả trước khi thư viện analytics.js được tải đầy đủ. Ngay khi thư viện analytics.js được tải, các mục trong hàng đợi lệnh sẽ được thực thi theo thứ tự nhận được. Sau khi hoàn tất thao tác này, các lệnh mới được đẩy vào hàng đợi sẽ được thực thi ngay lập tức.

Để giữ cho đoạn mã theo dõi nhỏ nhất có thể, hàng đợi lệnh ga() bị quá tải để chấp nhận các đối số ở nhiều định dạng. Tài liệu này trình bày chi tiết tất cả các cách gọi hàm hàng đợi lệnh ga().

Chữ ký hàm
ga(command, [...fields], [fieldsObject])

Việc gọi hàm hàng đợi lệnh ga() có chữ ký hàm sau sẽ đẩy các lệnh vào hàng đợi để được lên lịch thực thi sau khi thư viện được tải.

ga(readyCallback)

Gọi hàm hàng đợi lệnh ga() bằng cách truyền hàm này vào hàm sẽ lên lịch hàm đã truyền để thực thi tại điểm tiếp theo trong hàng đợi.

Vì các lệnh chỉ được thực thi sau khi thư viện analytics.js được tải đầy đủ, lý do phổ biến nhất để chuyển hàng đợi lệnh một hàm là lệnh gọi lại khi thư viện analytics.js được tải và sẵn sàng.

Thêm lệnh vào hàng đợi

Việc gọi hàm hàng đợi lệnh ga() có chữ ký hàm sau sẽ đẩy các lệnh vào hàng đợi để được lên lịch thực thi sau khi thư viện được tải.

Cách sử dụng

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

Các tham số

Tên Loại Bắt buộc Nội dung mô tả
command string

Giá trị nhận dạng đại diện cho lệnh cần thêm vào hàng đợi. Mã nhận dạng gồm ba phần (phần đầu là tùy chọn):

[trackerName.][pluginName:]methodName
trackerName Tên của trình theo dõi để gọi lệnh đã lên lịch. Nếu không có tên trình theo dõi nào được chỉ định, lệnh này sẽ được gọi trên trình theo dõi mặc định.
pluginName Tên của một trình bổ trợ analytics.js bắt buộc. Nếu chỉ định pluginName, thì methodName phải là một phương thức do trình bổ trợ cung cấp.
methodName Tên của phương thức sẽ được lên lịch để thực thi. Khi không chỉ định tên trình bổ trợ, phương thức này phải là một trong những phương thức lệnh liệt kê dưới đây.
...fields * no Một hoặc nhiều thông số tiện lợi tùy chọn để nhanh chóng chỉ định các trường phổ biến. Số lượng và trường cụ thể được phép thay đổi tùy thuộc vào phương thức lệnh đang được gọi.
fieldsObject Object no

Một đối tượng để chỉ định các giá trị còn lại chưa được chỉ định trong bất kỳ tham số fields nào.

Nếu bạn đặt một trường trong cả thông số fieldsfieldsObject, thì giá trị trong fieldsObject sẽ được sử dụng.

Xem tài liệu tham khảo về trường để biết tài liệu dành riêng cho từng trường.

Ví dụ

Hãy xem mục phương thức lệnh bên dưới để biết các ví dụ về lệnh riêng lẻ.

Lệnh gọi lại đã sẵn sàng

Gọi hàm hàng đợi lệnh ga() bằng cách truyền hàm này vào hàm sẽ lên lịch hàm đã truyền để thực thi tại điểm tiếp theo trong hàng đợi.

Vì các lệnh chỉ được thực thi sau khi thư viện analytics.js được tải đầy đủ, lý do phổ biến nhất để chuyển hàng đợi lệnh một hàm là lệnh gọi lại khi thư viện analytics.js được tải và sẵn sàng.

Cách sử dụng

ga(readyCallback)

Các tham số

Tên Loại Bắt buộc Nội dung mô tả
readyCallback Function

Hàm callback được gọi khi thư viện được tải đầy đủ và sẵn sàng tương tác. Hàm này được gọi bằng đối tượng trình theo dõi mặc định làm đối số đầu tiên. Nếu chưa tạo trình theo dõi mặc định nào, đối số đầu tiên là undefined.

Lưu ý: khi hàm callback được gọi, tất cả phương thức đối tượng ga đều có sẵn để sử dụng.

Ví dụ

// 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`.
});

Thông tin chi tiết về phương thức lệnh

Sau đây là danh sách tất cả phương thức có thể chuyển vào hàng đợi lệnh ga() (ngoại trừ các phương thức trình bổ trợ).

create

Tạo một bản sao trình theo dõi mới với các trường được chỉ định.

Cách sử dụng

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

Các tham số

Xem tài liệu tham khảo về trường để biết tài liệu dành riêng cho từng trường.

Trả về

undefined

Ví dụ

// 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

Gửi một lượt truy cập đến Google Analytics.

Cách sử dụng

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

Các trường được gửi là giá trị được chỉ định trong các thông số ...fieldsfieldsObject, được hợp nhất với các trường hiện được lưu trữ trên trình theo dõi.

Các tham số

Các trường mà thông số ...fields có thể chỉ định sẽ khác nhau tùy thuộc vào loại lượt truy cập. Bảng sau đây liệt kê các trường tương ứng với từng loại lượt truy cập. Các loại lượt truy cập không được liệt kê không chấp nhận các thông số ...fields mà chỉ chấp nhận fieldsObject.

Loại truy cập ...fields
pageview page
event eventCategory, eventAction, eventLabel, eventValue
social socialNetwork, socialAction, socialTarget
timing timingCategory, timingVar, timingValue, timingLabel

Xem tài liệu tham khảo về trường để biết tài liệu dành riêng cho từng trường.

Trả về

undefined

Ví dụ

// 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

Đặt một cặp trường và giá trị hoặc một nhóm các cặp trường/giá trị trên đối tượng trình theo dõi.

Cách sử dụng

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

Các tham số

Xem tài liệu tham khảo về trường để biết tài liệu dành riêng cho từng trường.

Trả về

undefined

Ví dụ

// 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

Yêu cầu trình bổ trợ analytics.js.

Cách sử dụng

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

Các tham số

Tên Loại Bắt buộc Nội dung mô tả
pluginName string Tên của trình bổ trợ bắt buộc. Lưu ý: nếu trình bổ trợ này không phải là một trình bổ trợ analytics.js chính thức, thì trình bổ trợ này phải được cung cấp ở nơi khác trên trang.
pluginOptions Object no Một đối tượng khởi tạo sẽ được chuyển đến hàm khởi tạo trình bổ trợ khi tạo bản sao.

Trả về

undefined

Ví dụ:

// 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

Cung cấp một trình bổ trợ analytics.js và các phương thức sử dụng nó cùng với hàng đợi lệnh ga().

ga('provide', pluginName, pluginConstuctor);

Các tham số

Tên Loại Bắt buộc Nội dung mô tả
pluginName string Tên của trình bổ trợ đang được cung cấp. Tên bạn dùng phải giống với tên mà bất kỳ lệnh gọi yêu cầu nào cũng sử dụng.
pluginConstuctor Function Hàm khởi tạo hàm cung cấp tất cả các phương thức và logic của trình bổ trợ. Hàm khởi tạo này sẽ được gọi bằng đối tượng pluginsOptions đã chỉ định trong phương thức required.

Ví dụ:

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

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

remove

Xoá đối tượng trình theo dõi.

Cách sử dụng

ga('[trackerName.]remove');

Ví dụ

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