API thẻ Google (gtag.js) bao gồm một chức năng duy nhất là gtag()
với
cú pháp sau:
gtag(<command>, <command parameters>);
<command>
là một trong những lệnh sau:<command parameters>
là các tham số bạn có thể truyền đếngtag()
. Lệnh các tham số khác nhau tùy theo lệnh; tham chiếu đến tham chiếu lệnh, bên dưới.
Bạn có thể gọi các lệnh gtag()
ở bất cứ đâu trên trang của mình, miễn là lệnh của bạn
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
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 riêng lẻ, 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ả các sự kiện. Điều này đạt được bằng cách sử dụng
các lệnh event
, config
và set
.
Các giá trị thông số được đặt trong một phạm vi không sửa đổi các giá trị được đặt cho cùng một phạm vi
tham số ở 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 set
. Sau khi cả hai lệnh được thực thi, giá trị chung của campaign_id
là
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 thông 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, chỉ
một giá trị duy nhất được sử dụng khi xử lý sự kiện. Giá trị thông số nằm trong phạm vi
event
sẽ được ưu tiên hơn các thông số trong phạm vi config
và 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 là thường là cấu hình theo sản phẩm cụ thể cho một sản phẩm, nhưng bạn chỉ cần định cấu hình điều này một lần nếu bạn đ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 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 đị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ẻ cho thẻ Google.
Dưới đây là ví dụ minh hoạ cách gửi thêm thông tin về cấu hình
định cấu hình một thẻ để gửi dữ liệu đến tài khoản Analytics bằng
Tham số send_page_view
truyền giá trị false
và groups
sẽ 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ị 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 |
Mục tiêu để tìm nạp các giá trị. |
<field_name> | FieldName | client_id | Tên của trường cần tải. |
số gọi lại | Function |
(field) => console.log(field) |
Một hàm sẽ được gọi bằng trường được yêu cầu, hoặc
|
FieldName
Tên trường có thể là tên của trường tuỳ chỉnh mà bạn đặt bằng gtag('set')
hoặc một trong các giá trị sau:
Tên trường | Các mục tiêu được hỗ trợ |
---|---|
client_id |
|
session_id |
|
gclid |
|
Ví dụ
Lấy giá trị thành lời hứa
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 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ẻ chiến dịch các thông số để các thẻ có thể truy cập được qua nhiều thẻ trên cùng một trang.
Ví dụ bên dưới minh hoạ cách đặt tên và mã chiến dịch cho ngày thứ Sáu đen
sự kiện mua sắm. Vì bạn đã sử dụng set
, nên tất cả thẻ khác, chẳng hạn như
Thẻ Sự kiện GA4 hoặc thẻ Tái tiếp thị của Google Ads 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à:
- Một sự kiện được đề xuất. Mỗi sự kiện được đề xuất có thể mất khoảng thời gian tham số được đề xuất.
- Sự kiện tuỳ chỉnh. Sự kiện tuỳ chỉnh là một tên sự kiện tuỳ ý do 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 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 sẽ kích hoạt sự kiện screen_view
được đề xuất với 2
tham 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 trạng thái đồng ý.
gtag('consent', {<consent_arg>}, {<consent_params>});
Hãy xem mục sự đồng ý trong trung tâm trợ giúp để biết thêm thông tin về cách hành vi của những người dùng này định cấu hình tham số.
<consent_arg>
là một trong số 'default'
hoặc 'update'
. 'default'
được dùng để đặt
thông số đồng ý mặc định nên được sử dụng và 'update'
được dùng để
hãy 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ị được 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 mã 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ữ, 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 tính bằng mili giây để chờ một cuộc gọi cập nhật thông tin về trạng thái đồng ý. |