Tài liệu tham khảo API về thẻ Google

API thẻ Google (gtag.js) bao gồm một hàm duy nhất là gtag(), với cú pháp sau:

gtag(<command>, <command parameters>);

• <command> là một trong các lệnh sau:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> là các thông số bạn có thể truyền đến gtag(). Các tham số lệnh sẽ khác nhau tuỳ theo lệnh; hãy tham khảo tài liệu tham khảo về lệnh bên dưới.

Bạn có thể gọi các lệnh gtag() ở bất kỳ vị trí nào trên trang, miễn là các lệnh đó xuất hiện bên dưới đoạn mã thẻ Google. Để tìm hiểu cách thêm đoạn mã vào một trang, hãy xem hướng dẫn cài đặt.

Phạm vi của thông số

Bạn có thể đặt phạm vi giá trị thông số cho từng sự kiện, tất cả sự kiện được gửi đến một <TARGET_ID> cụ thể hoặc trên toàn cầu cho tất cả sự kiện. Bạn có thể thực hiện việc này bằng cách sử dụng các lệnh event, config và set.

Các giá trị tham số được đặt trong một phạm vi sẽ không sửa đổi các giá trị được đặt cho cùng một tham số trong một phạm vi khác. Trong ví dụ bên dưới, lệnh config không sửa đổi giá trị toàn cục cho campaign_id được chỉ định trước đó bằng lệnh set. Sau khi cả hai lệnh được thực thi, giá trị chung của campaign_id vẫn là '1234'.

// Set global campaign ID
gtag('set', { 'campaign_id': '1234' });

// Set campaign ID for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'campaign_id': 'ABCD' });

Mức độ ưu tiên của tham số

Nếu bạn chỉ định các giá trị khác nhau cho cùng một thông số trong các phạm vi khác nhau, thì hệ thống sẽ chỉ sử dụng một giá trị duy nhất khi xử lý sự kiện. Các giá trị tham số có phạm vi là event sẽ được ưu tiên hơn các tham số có phạm vi là config và các tham số config sẽ được ưu tiên hơn các tham số có phạm vi toàn cầu bằng cách sử dụng set.

// Set campaign information at the global scope
gtag('set', { 'campaign_name': 'Black Friday Sale' });

// Set currency for <TARGET_ID1> to 'USD'
gtag('config','<TARGET_ID1>', { 'currency': 'USD' });

// Process a conversion event with currency: 'GBP'
gtag('event','conversion', { 'currency': 'GBP', 'send_to': '<TARGET_ID1>' });

// Process a conversion event with currency: 'EUR'
gtag('event','conversion');

// Process a conversion event with currency: 'USD'
gtag('event','conversion', { 'send_to': '<TARGET_ID1>' });

config

Cho phép bạn thêm thông tin cấu hình bổ sung vào các mục tiêu. Đây thường là cấu hình dành riêng cho sản phẩm của một sản phẩm, nhưng bạn chỉ cần định cấu hình một lần nếu đang sử dụng cả Google Ads và Google Analytics.

gtag('config', '<TARGET_ID>', {<additional_config_info>});

<TARGET_ID> là giá trị nhận dạng xác định duy nhất mục tiêu cho các lượt truy cập, chẳng hạn như một tài sản Google Analytics hoặc một tài khoản Google Ads. <additional_config_info> là một hoặc nhiều cặp giá trị thông số.

Ví dụ này định cấu hình một thẻ để gửi dữ liệu đến tài khoản Google Ads:

gtag('config', 'TAG_ID');

trong đó "TAG_ID" là mã thẻ của thẻ Google.

Để minh hoạ cách gửi thông tin cấu hình bổ sung, sau đây là một ví dụ định cấu hình thẻ để gửi dữ liệu đến một tài khoản Analytics có tham số send_page_view truyền giá trị false và tham số groups truyền giá trị 'agency'.

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

get

Cho phép bạn lấy nhiều giá trị khác nhau từ gtag.js, bao gồm cả các giá trị được đặt bằng lệnh set.

gtag('get', '<target>', '<field_name>', callback)

Đối số	Loại	Ví dụ:	Mô tả
<target>	string	G-XXXXXXXXXX	Đích để tìm nạp giá trị.
<field_name>	FieldName	client_id	Tên của trường cần lấy.
callback	Function	(field) => console.log(field)	Một hàm sẽ được gọi với trường được yêu cầu hoặc undefined nếu trường này không được đặt.

FieldName

Tên trường có thể là tên của một trường tuỳ chỉnh mà bạn đặt bằng lệnh gtag('set') hoặc một trong các giá trị sau:

Tên trường	Mục tiêu được hỗ trợ
client_id	Google Analytics 4
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

Lưu ý: Nếu bạn sử dụng lệnh set với những tên trường này, thì giá trị bạn đặt sẽ được ưu tiên.

Ví dụ

Nhận giá trị vào một Promise

const gclidPromise = new Promise(resolve => {
  gtag('get', 'DC-XXXXXXXX', 'gclid', resolve)
});

gclidPromise.then((gclid) => {
  // Do something with gclid...
})

Gửi sự kiện đến Measurement Protocol

gtag('get', 'G-XXXXXXXXXX', 'client_id', (clientID) => {
  sendOfflineEvent(clientID, "tutorial_begin")
});

function sendOfflineEvent(clientID, eventName, eventData) {
  // Send necessary data to your server...
}

Nhận giá trị mà bạn đặt

gtag('set', {campaign_name: 'Spring_Sale'});

gtag('get', 'G-XXXXXXXXXX', 'campaign_name', (campaign_name) => {
  // Do something with currency value you set earlier.
})

set

Lệnh set cho phép bạn xác định các thông số sẽ được liên kết với mọi sự kiện tiếp theo trên trang.

Lưu ý: Bạn nên sử dụng các lệnh config hoặc event bất cứ khi nào có thể.

gtag('set', {<parameter-value-pair>, <parameter-value-pair>});

Ví dụ: bạn có thể chia sẻ các tham số chiến dịch để nhiều thẻ trên cùng một trang có thể truy cập vào các tham số đó.

Ví dụ bên dưới minh hoạ cách đặt tên và mã chiến dịch cho một sự kiện mua sắm vào Thứ Sáu Đen. Vì bạn đã sử dụng set, nên tất cả các thẻ khác (ví dụ: thẻ Sự kiện GA4 hoặc thẻ Tái tiếp thị của Google Ads) đều có thể truy cập vào dữ liệu này.

gtag('set', 'campaign', {
  'id': 'abc',
  'source': 'google',
  'name': 'black_friday_promotion',
  'term': 'running+shoes',
});

event

Sử dụng lệnh event để gửi dữ liệu sự kiện.

gtag('event', '<event_name>', {<event_params>});

<event_name> có thể là:

• Một sự kiện được đề xuất. Mỗi sự kiện được đề xuất có thể lấy các thông số được đề xuất.
• Một sự kiện tuỳ chỉnh. Sự kiện tuỳ chỉnh là tên sự kiện tuỳ ý do bạn đặt, cùng với các thông số tuỳ ý. Để biết thêm thông tin, hãy xem bài viết Thiết lập sự kiện.

<event_params> là một hoặc nhiều cặp giá trị thông số. Mỗi cặp được phân tách bằng dấu phẩy.

Lệnh event sau đây kích hoạt sự kiện được đề xuất screen_view với 2 thông số: app_name và screen_name.

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

Quan trọng: Đoạn mã thẻ Google phải xuất hiện trên cùng một trang, phía trên các lệnh event, nếu không dữ liệu của bạn sẽ không được gửi.

consent

Sử dụng lệnh consent để định cấu hình sự đồng ý.

gtag('consent', {<consent_arg>}, {<consent_params>});

Hãy xem phần sự đồng ý trong trung tâm trợ giúp để biết thêm thông tin về hành vi mà các thông số này định cấu hình.

<consent_arg> là một trong 'default' hoặc 'update'. 'default' được dùng để đặt các thông số đồng ý mặc định cần sử dụng và 'update' được dùng để cập nhật các thông số này sau khi người dùng cho biết sự đồng ý của họ.

Các <consent_params> sau đây được hỗ trợ:

Tên trường	Giá trị cho phép	Mô tả
ad_storage	'granted' | 'denied'	Cho phép việc lưu trữ, chẳng hạn như cookie (web) hoặc giá trị nhận dạng thiết bị (ứng dụng), có liên quan đến quảng cáo.
ad_user_data	'granted' | 'denied'	Đặt trạng thái đồng ý đối với việc gửi dữ liệu người dùng đến Google cho mục đích quảng cáo.
ad_personalization	'granted' | 'denied'	Đặt trạng thái đồng ý cho quảng cáo được cá nhân hoá.
analytics_storage	'granted' | 'denied'	Cho phép việc lưu trữ dữ liệu, chẳng hạn như cookie (web) hoặc giá trị nhận dạng ứng dụng (ứng dụng), có liên quan đến số liệu phân tích, chẳng hạn như thời lượng truy cập.
wait_for_update	số nguyên dương bất kỳ	Đặt thời gian chờ tính bằng mili giây cho một lệnh gọi cập nhật sự đồng ý.