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>);

Bạn có thể gọi các lệnh gtag() ở bất kỳ đâu 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 tham số

Bạn có thể đặt phạm vi giá trị tham số cho từng sự kiện, tất cả sự kiện được gửi đến a specific <TARGET_ID>, 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ụ sau, lệnh config không sửa đổi giá trị toàn cầu cho campaign_id đã được gán trước đó bằng lệnh set. Sau khi cả hai lệnh được thực thi, giá trị toàn cầu 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 gán cho cùng một tham số trong các phạm vi khác nhau, thì chỉ một giá trị được sử dụng khi xử lý sự kiện. Các giá trị tham số có phạm vi là event sẽ có mức độ ưu tiên cao hơn các tham số có phạm vi là config và các tham số config có mức độ ưu tiên cao 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 đối với 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>});

Các điểm chính về <TARGET_ID>:

  • The <TARGET_ID> trong lệnh gtag('config', <TARGET_ID>, ...) là Mã thẻ xác định vị trí mà gtag.js sẽ gửi dữ liệu sự kiện. Đây có thể là một đích đến như tài sản Google Analytics, tài khoản Google Ads, cấu hình Floodlight hoặc thẻ Google có nhiều đích đến.

  • Mã thẻ (chẳng hạn như GT-XXXXXX, G-XXXXXX hoặc AW-YYYYYY) là giá trị nhận dạng cho thẻ Google. Bạn thêm mã này vào mã trang web để tải thẻ Google.

  • Bạn có thể định cấu hình một thẻ Google (được xác định bằng Mã thẻ) để gửi dữ liệu đến nhiều đích đến. Mặc dù một số Mã thẻ có thể trông giống với Mã đích đến, chẳng hạn như G-XXXXXX cho một tài sản Google Analytics hoặc AW-YYYYYY cho một tài khoản Google Ads, nhưng <TARGET_ID> trong lệnh config đề cập đến thực thể cụ thể của thẻ Google được tải trên trang.

  • Lệnh gtag('config', ...) định cấu hình hành vi của thẻ Google được liên kết với <TARGET_ID> cụ thể đó. Mặc dù Mã thẻ có trong tập lệnh src thường tải thẻ Google, nhưng bạn có thể sử dụng bất kỳ Mã thẻ hợp lệ nào được liên kết với tài khoản của mình trong lệnh gtag('config').

  • Một thẻ Google có thể có nhiều Mã thẻ được liên kết với thẻ đó, thường là do việc hợp nhất thẻ. Bạn có thể sử dụng bất kỳ mã nào trong số các mã được liên kết này trong tham số src của tập lệnh để tải thẻ Google.

  • Nếu đang gửi dữ liệu đến nhiều đích đến hoặc sử dụng nhiều thẻ, bạn chỉ cần đưa một đoạn mã thẻ Google có một Mã thẻ vào src của tập lệnh. Sau đó, bạn đưa lệnh gtag('config') cho mỗi Mã thẻ hoặc đích đến bổ sung.

<additional_config_info> là một hoặc nhiều cặp giá trị tham 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ẻ cho 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 một thẻ để gửi dữ liệu đến 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. Nếu trường này không được đặt, hàm sẽ được gọi với đối số undefined.

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 Các 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

Ví dụ

Lấy 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...
}

Lấy 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ẻ 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ụ 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 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à:

<event_params> là một hoặc nhiều cặp giá trị tham 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 hai tham số: app_name và screen_name.

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

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

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

Hãy xem phần đồ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 các giá trị 'default' hoặc 'update'. 'default' được dùng để đặt các tham số đồng ý mặc định cần sử dụng và '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ợ:

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 (trên 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ữ (chẳng hạn như cookie (trên 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, ví dụ: thời lượng truy cập.
wait_for_update bất kỳ số nguyên dương nào Đặt thời gian tính bằng mili giây để chờ lệnh gọi cập nhật sự đồng ý.