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.

Lưu ý: Đoạn mã theo dõi JavaScript cho phép đổi tên hàm hàng đợi lệnh ga(). Nếu bạn làm như vậy, hãy đảm bảo bất kỳ mã nào bạn sao chép từ trang web này đều tham chiếu đến tên mới.

Để 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	có	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ố fields và fieldsObject, 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	có	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'
});

Quan trọng: bạn không thể chỉ định tên trình theo dõi trong phần phương thức của lệnh gọi tạo. Ví dụ: ga('myTracker.create', 'UA-XXXXX-Y`) không hoạt động.

Để biết thêm thông tin về cách tạo trình theo dõi, hãy đọc hướng dẫn tạo trình theo dõi.

---

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ố ...fields và fieldsObject, được hợp nhất với các trường hiện được lưu trữ trên trình theo dõi.

Lưu ý: các giá trị được chỉ định trong ...fields và fieldsObject được gửi đến lượt truy cập hiện tại, nhưng các giá trị này không được lưu trữ trên đối tượng trình theo dõi. Sử dụng phương thức set để cập nhật 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
});

Để biết thêm thông tin về cách gửi lượt truy cập, hãy đọc hướng dẫn về cách gửi dữ liệu đến Google Analytics.

---

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

Để biết thêm thông tin về cách cập nhật trình theo dõi, hãy đọc hướng dẫn tải và thiết lập dữ liệu trình theo dõi.

---

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	có	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'
});

Để biết thêm thông tin về cách yêu cầu trình bổ trợ analytics.js, hãy đọc hướng dẫn sử dụng trình bổ trợ.

---

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

Lưu ý: Không giống như hầu hết phương thức hàng đợi ga(), cung cấp không chấp nhận tên trình theo dõi.

Các tham số

Tên	Loại	Bắt buộc	Nội dung mô tả
pluginName	string	có	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	có	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);

Để biết thêm thông tin về cách cung cấp trình bổ trợ analytics.js, hãy đọc hướng dẫn viết trình bổ trợ.

---

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