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(), có cú pháp như 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 tham số bạn có thể truyền đến gtag(). Tham số lệnh thay đổi tuỳ theo lệnh; hãy tham khảo tài liệu tham khảo về lệnh.

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 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 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.

Giá trị tham số được đặt trong một phạm vi không sửa đổi giá trị được đặt cho cùng một tham số trong một phạm vi khác. Trong ví dụ sau, lệnh config không sửa đổi giá trị chung 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' });

Thứ tự ưu tiên của tham số

Nếu các giá trị khác nhau được chỉ định cho cùng một tham số trong các phạm vi khác nhau, thì chỉ một giá trị duy nhất được sử dụng khi xử lý sự kiện. Giá trị tham số trong phạm vi event sẽ được ưu tiên hơn tham số trong phạm vi config và tham số config được ưu tiên hơn tham số trong phạm vi chung 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>' });

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

gtag('config', 'TAG_ID');

trong đó "TAG_ID" là mã thẻ cho thẻ Google.

Để minh hoạ cách gửi thêm thông tin 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 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)

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:

Ví dụ

Nhận giá trị vào 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...
}

Lấy 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 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ẻ 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ụ sau đây 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ị trên 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> là:

• Sự kiện được đề xuất. Mỗi sự kiện được đề xuất có thể nhận các tham số được đề 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 tham 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 có hai tham số: app_name và screen_name.

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

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 tham 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 tham số đồng ý mặc định cần sử dụng, còn 'update' được dùng để cập nhật các tham 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ợ: