Referensi Google tag API

Google tag (gtag.js) API terdiri dari satu fungsi, gtag(), dengan sintaksis berikut:

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

• <command> adalah salah satu dari perintah berikut:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> adalah parameter yang dapat Anda teruskan ke gtag(). Parameter perintah bervariasi sesuai dengan perintah; lihat referensi perintah.

Anda dapat memanggil perintah gtag() di mana saja di halaman Anda, asalkan perintah Anda muncul di bawah cuplikan tag Google. Untuk mempelajari cara menambahkan cuplikan ke sebuah halaman, lihat panduan penginstalan.

Cakupan parameter

Anda dapat menentukan cakupan nilai parameter ke setiap peristiwa, ke semua peristiwa yang dikirim ke <TARGET_ID> spesifik, atau secara global ke semua peristiwa. Untuk melakukannya, gunakan perintah event, config, dan set.

Nilai parameter yang ditetapkan dalam satu cakupan tidak mengubah nilai yang ditetapkan untuk parameter yang sama dalam cakupan berbeda. Dalam contoh berikut, perintah config tidak mengubah nilai global untuk campaign_id yang sebelumnya ditetapkan dengan perintah set. Setelah kedua perintah dijalankan, nilai global campaign_id masih '1234'.

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

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

Prioritas parameter

Jika nilai yang berbeda ditetapkan ke parameter yang sama dalam cakupan berbeda, hanya satu nilai yang akan digunakan saat memproses peristiwa. Nilai parameter yang memiliki cakupan event akan lebih diprioritaskan dari parameter yang memiliki cakupan config, dan parameter config akan lebih diprioritaskan dari parameter cakupan global yang menggunakan 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

Memungkinkan Anda menambahkan informasi konfigurasi tambahan ke target. Konfigurasi tambahan ini biasanya merupakan konfigurasi spesifik per produk, tetapi Anda hanya perlu mengonfigurasinya satu kali jika menggunakan Google Ads dan Google Analytics.

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

Poin penting tentang <TARGET_ID>:

• <TARGET_ID> dalam perintah gtag('config', <TARGET_ID>, ...) adalah ID Tag yang mengidentifikasi tempat gtag.js harus mengirim data peristiwa. Tujuan ini dapat berupa properti Google Analytics, akun Google Ads, konfigurasi Floodlight, atau tag Google yang memiliki beberapa tujuan.

• ID Tag—seperti GT-XXXXXX, G-XXXXXX, atau AW-YYYYYY—adalah ID untuk tag Google Anda. Anda menambahkan ID ini ke kode situs untuk memuat tag Google.

• Satu tag Google (diidentifikasi berdasarkan ID Tag-nya) dapat dikonfigurasi untuk mengirim data ke beberapa tujuan. Meskipun beberapa ID Tag mungkin terlihat identik dengan ID Tujuan, seperti G-XXXXXX untuk properti Google Analytics atau AW-YYYYYY untuk akun Google Ads, <TARGET_ID> dalam perintah config merujuk ke instance tertentu dari tag Google yang dimuat di halaman.

• Perintah gtag('config', ...) mengonfigurasi perilaku tag Google yang terkait dengan <TARGET_ID> tertentu tersebut. Meskipun ID Tag yang disertakan dalam skrip src biasanya memuat tag Google, Anda dapat menggunakan ID Tag yang valid dan terkait dengan akun Anda dalam perintah gtag('config').

• Satu tag Google dapat memiliki beberapa ID Tag yang terkait dengannya, sering kali karena penggabungan tag. Salah satu ID terkait ini dapat digunakan dalam parameter src skrip untuk memuat tag Google.

• Jika Anda mengirim data ke beberapa tujuan atau menggunakan beberapa tag, Anda hanya perlu menyertakan satu cuplikan tag Google dengan satu ID Tag di skrip src. Kemudian, sertakan perintah gtag('config') untuk setiap ID Tag atau tujuan tambahan.

<additional_config_info> adalah satu atau beberapa pasangan parameter value.

Contoh ini mengonfigurasi tag untuk mengirim data ke akun Google Ads:

gtag('config', 'TAG_ID');

dengan "TAG_ID" adalah ID tag untuk tag Google.

Untuk menunjukkan cara mengirim informasi konfigurasi tambahan, berikut contoh yang mengonfigurasi tag untuk mengirim data ke akun Analytics dengan parameter send_page_view yang meneruskan nilai false, dan parameter groups yang meneruskan nilai 'agency'.

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

get

Memungkinkan Anda mendapatkan berbagai nilai dari gtag.js termasuk nilai yang ditetapkan dengan perintah set.

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

Argumen	Jenis	Contoh	Deskripsi
<target>	string	G-XXXXXXXXXX	Target untuk mengambil nilai.
<field_name>	FieldName	client_id	Nama kolom yang akan didapatkan.
callback	Function	(field) => console.log(field)	Fungsi yang akan dipanggil dengan kolom yang diminta, atau undefined jika tidak ditetapkan.

FieldName

Nama kolom dapat berupa nama kolom kustom yang Anda tetapkan dengan perintah gtag('set'), atau salah satu dari nilai berikut:

Nama Kolom	Target yang Didukung
client_id	Google Analytics 4
session_id	Google Analytics 4
session_number	Google Analytics 4
gclid	Google Ads Floodlight

Catatan: Jika Anda menggunakan perintah set dengan nama kolom ini, nilai yang Anda tetapkan akan diprioritaskan.

Contoh

Menyertakan nilai ke dalam Promise

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

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

Mengirim peristiwa ke Measurement Protocol

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

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

Mendapatkan nilai yang Anda tetapkan

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

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

set

Perintah set memungkinkan Anda menentukan parameter yang akan dikaitkan dengan setiap peristiwa berikutnya di halaman.

Catatan: Sebaiknya gunakan perintah config atau event jika memungkinkan.

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

Misalnya, Anda dapat membagikan parameter kampanye agar dapat diakses oleh beberapa tag di halaman yang sama.

Contoh berikut mengilustrasikan cara menetapkan nama dan ID kampanye untuk acara belanja Black Friday. Karena Anda telah menggunakan set, semua tag lainnya, misalnya, tag Peristiwa GA4 atau tag Pemasaran Ulang Google Ads, dapat mengakses data ini.

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

event

Gunakan perintah event untuk mengirim data peristiwa.

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

<event_name> adalah:

• Peristiwa yang direkomendasikan. Setiap peristiwa yang direkomendasikan dapat menggunakan parameter yang direkomendasikan.
• Peristiwa kustom. Peristiwa kustom adalah nama peristiwa arbitrer yang Anda buat, dengan parameter arbitrer. Untuk mengetahui informasi selengkapnya, lihat artikel Menyiapkan peristiwa.

<event_params> adalah satu atau beberapa pasangan parameter value. Setiap pasangan dipisahkan oleh koma.

Perintah event berikut mengaktifkan peristiwa screen_view yang direkomendasikan dengan dua parameter: app_name dan screen_name.

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

Penting: Cuplikan tag Google harus muncul di halaman yang sama, di atas perintah event, atau data Anda tidak akan dikirim.

consent

Gunakan perintah consent untuk mengonfigurasi izin.

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

Lihat izin di pusat bantuan untuk mengetahui informasi selengkapnya tentang perilaku yang dikonfigurasi oleh parameter ini.

<consent_arg> adalah salah satu dari 'default' atau 'update'. 'default' digunakan untuk menetapkan parameter izin default yang harus digunakan, dan 'update' digunakan untuk memperbarui parameter ini setelah pengguna menunjukkan izin mereka.

<consent_params> berikut ini didukung:

Nama Kolom	Nilai yang Diizinkan	Deskripsi
ad_storage	'granted' | 'denied'	Memungkinkan penyimpanan, seperti cookie (web) atau ID perangkat (aplikasi), yang terkait dengan iklan.
ad_user_data	'granted' | 'denied'	Menetapkan izin pengiriman data pengguna ke Google untuk tujuan iklan.
ad_personalization	'granted' | 'denied'	Menetapkan izin untuk iklan yang dipersonalisasi.
analytics_storage	'granted' | 'denied'	Memungkinkan penyimpanan, seperti cookie (web) atau ID aplikasi (aplikasi), yang terkait dengan analisis, misalnya, durasi kunjungan.
wait_for_update	bilangan bulat positif apa pun	Menetapkan waktu dalam milidetik untuk menunggu panggilan pembaruan izin.