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:<command parameters>
là các tham số bạn có thể truyền đếngtag()
. Các tham số lệnh khác nhau tuỳ theo lệnh; hãy tham khảo nội dung tham khảo lệnh ở bên dưới.
Bạn có thể gọi các lệnh gtag()
ở bất kỳ đâu trên trang của mình, 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 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 cho tất cả sự kiện trên toàn cầu. 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ị chung cho campaign_id
đã 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 các giá trị khác nhau được chỉ định cho cùng một thông số trong các phạm vi khác nhau, thì chỉ một giá trị được dùng khi xử lý sự kiện. Giá trị thông số trong phạm vi event
sẽ được ưu tiên hơn các thông số trong phạm vi config
, và các thông số config
được ưu tiên hơn các thông số có phạm vi trên 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 mục tiêu. Đây thường là cấu hình dành riêng cho 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 riêng mục tiêu cho các lượt truy cập,
chẳng hạn như tài sản Google Analytics hoặc tài khoản Google Ads.
<additional_config_info>
là một hoặc nhiều cặp thông số-giá trị.
Ví dụ sau đâ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êm thông tin về cấu hình, dưới đây là ví dụ về cách định cấu hình thẻ để gửi dữ liệu đến tài khoản Analytics bằng thông số send_page_view
truyền giá trị false
và thông số groups
truyền giá trị 'agency'
.
gtag('config', 'TAG_ID', {
'send_page_view': false,
'groups': 'agency'
});
get
Cho phép bạn nhận nhiều giá trị 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ụ: | Nội dung mô tả |
---|---|---|---|
<target> | string |
G-XXXXXXXXXX |
Mục tiêu để tìm nạp giá trị. |
<field_name> | FieldName | client_id | Tên của trường cần lấy. |
số gọi lại | Function |
(field) => console.log(field) |
Một hàm sẽ được gọi bằng trường yêu cầu hoặc |
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 |
|
session_id |
|
gclid |
|
Ví dụ
Biến lời hứa thành giá trị
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ị 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 đặt cho phép bạn xác định các tham số sẽ được liên kết với mọi sự kiện tiếp theo trên trang.
gtag('set', {<parameter-value-pair>, <parameter-value-pair>});
Ví dụ: bạn có thể chia sẻ các thông số chiến dịch để nhiều thẻ trên cùng một trang có thể truy cập vào các thông 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 ngày 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
Dùng lệnh event
để gửi dữ liệu sự kiện.
gtag('event', '<event_name>', {<event_params>});
<event_name>
có thể là:
- Sự kiện được đề xuất. Mỗi sự kiện được đề xuất có thể lấy các thông số đề xuất.
- Sự kiện tuỳ chỉnh. Sự kiện tuỳ chỉnh là tên sự kiện tuỳ ý mà bạn tạo, với các thông số tuỳ ý (tức là tuỳ chỉnh). Ví dụ: hãy xem cách sử dụng các sự kiện tuỳ chỉnh trong Google Analytics.
<event_params>
là một hoặc nhiều cặp thông số-giá trị. 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 đề xuất screen_view
với hai
thông số: app_name
và screen_name
.
gtag('event', 'screen_view', {
'app_name': 'myAppName',
'screen_name': 'Home'
});
consent
Dùng lệnh consent
để định cấu hình chế độ đồng ý.
gtag('consent', {<consent_arg>}, {<consent_params>});
Hãy xem phần lấy 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 số 'default'
hoặc 'update'
. 'default'
được dùng để đặt
các thông số về sự đồng ý mặc định mà bạn nê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 thể hiện sự đồng ý.
<consent_params>
sau đây được hỗ trợ:
Tên trường | Giá trị được phép | Nội dung 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 sự đồng ý cho 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' |
Bật bộ nhớ, 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 phân tích, ví dụ: thời lượng truy cập. |
wait_for_update |
số nguyên dương bất kỳ | Đặt thời gian tính bằng mili giây để chờ cuộc gọi cập nhật về sự đồng ý. |