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

Hàng đợi lệnh ga() cung cấp một 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 sau 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 việc này, các lệnh mới đẩ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 mọi đoạn mã mà bạn sao chép từ trang web này đều tham chiếu tên mới.

Để giữ cho đoạn mã theo dõi có kích thước nhỏ nhất có thể, hàng đợi lệnh ga() bị nạp chồng để 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])	Nếu bạn gọi hàm hàng đợi lệnh ga() bằng chữ ký hàm sau, thì các lệnh sẽ được đẩy vào hàng đợi cần được lên lịch thực thi sau khi thư viện được tải.
ga(readyCallback)	Việc gọi hàm hàng đợi lệnh ga() bằng cách truyền hàm đó vào một hàm sẽ lên lịch hàm đã truyền để thực thi ở đ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 đủ, nên lý do phổ biến nhất để chuyển hàng đợi lệnh của một hàm là dưới dạng 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

Nếu bạn gọi hàm hàng đợi lệnh ga() bằng chữ ký hàm sau, thì các lệnh sẽ được đẩy vào hàng đợi cần đượ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])

Tham số

Tên	Loại	Bắt buộc	Nội dung mô tả
command	string	có	Giá trị nhận dạng biểu thị lệnh cần thêm vào hàng đợi. Mã nhận dạng này bao gồm 3 phần (hai phần đầu là không bắt buộc): [trackerName.][pluginName:]methodName trackerName Tên của thiết bị theo dõi để gọi lệnh đã lên lịch. Nếu bạn không chỉ định tên thiết bị theo dõi, lệnh này sẽ được gọi trên thiết bị 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 bạn chỉ định pluginName, 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 đượ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 các phương thức lệnh được liệt kê bên dưới.
...fields	*	no	Một hoặc nhiều tham số tiện lợi không bắt buộc để chỉ định nhanh các trường phổ biến. Số lượng và các trường cụ thể được cho phép sẽ khác nhau tuỳ thuộc vào phương thức lệnh đang được gọi.
fieldsObject	Object	no	Đối tượng để chỉ định mọi 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ả tham 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ừng tài liệu về trường.

Ví dụ

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

Sẵn sàng gọi lại

Việc gọi hàm hàng đợi lệnh ga() bằng cách truyền hàm đó vào một hàm sẽ lên lịch hàm đã truyền để thực thi ở đ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 đủ, nên lý do phổ biến nhất để chuyển hàng đợi lệnh của một hàm là dưới dạng 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)

Tham số

Tên	Loại	Bắt buộc	Nội dung mô tả
readyCallback	Function	có	Một hàm callback sẽ được gọi khi thư viện được tải đầy đủ và sẵn sàng để bạn 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 bạn chưa tạo trình theo dõi mặc định, đối số đầu tiên sẽ là undefined. Lưu ý: khi hàm callback được gọi, bạn có thể sử dụng mọi phương thức đối tượng ga.

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ể được chuyển vào hàng đợi lệnh ga() (ngoại trừ các phương thức trong trình bổ trợ).

create

Tạo một thực thể trình theo dõi mới có các trường được chỉ định.

Cách sử dụng

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

Tham số

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

Giá trị 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'
});

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

Lưu ý: các giá trị được chỉ định trong ...fields và fieldsObject được gửi cùng với lượt truy cập hiện tại, nhưng không được lưu trữ trên đối tượng công cụ theo dõi. Sử dụng phương thức set để cập nhật trình theo dõi.

Tham số

Các trường có thể được chỉ định theo thông số ...fields sẽ khác nhau tuỳ 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 thông số ...fields, mà chỉ chấp nhận thông số fieldsObject.

Loại lượt 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ừng tài liệu về trường.

Giá trị 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 gửi dữ liệu đến Google Analytics.

---

set

Thiết lập một cặp trường và giá trị duy nhất hoặc một nhóm cặp trường/giá trị trên một đố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);

Tham số

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

Giá trị 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 các thiết bị theo dõi, hãy đọc hướng dẫn nhận và cài đặt dữ liệu thiết bị theo dõi.

---

require

Yêu cầu phải có trình bổ trợ analytics.js.

Cách sử dụng

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

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ợ cần thiết. Lưu ý: nếu không phải là trình bổ trợ analytics.js chính thức, thì trình bổ trợ đó 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 truyền đến hàm khởi tạo trình bổ trợ khi tạo bản sao.

Giá trị 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ề việc 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 của trình bổ trợ đó để sử dụng với hàng đợi lệnh ga().

ga('provide', pluginName, pluginConstuctor);

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

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 được dùng phải giống với tên mà mọi lệnh gọi require sử dụng.
pluginConstuctor	Function	có	Hàm khởi tạo cung cấp tất cả logic và phương thức của trình bổ trợ. Hàm khởi tạo này sẽ được gọi bằng đối tượng pluginsOptions được chỉ định trong phương thức require.

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 về cách 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');