Referensi API tag situs global

API tag situs global (gtag.js) 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 akan diteruskan ke gtag(). Parameter perintah bervariasi sesuai dengan perintah; lihat referensi perintah, di bawah ini.

Anda dapat memanggil perintah gtag di mana saja di halaman, selama perintah Anda muncul di bawah cuplikan global. Untuk mempelajari cara menambahkan cuplikan global ke halaman, lihat panduan penginstalan.

`config`

Memungkinkan Anda menambahkan informasi konfigurasi tambahan ke target. Perintah ini biasanya merupakan konfigurasi khusus produk untuk produk seperti Google Ads atau Google Analytics.

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

<TARGET_ID> adalah ID yang mengidentifikasi target untuk hit secara unik, seperti properti Google Analytics atau akun Google Ads. <additional_config_info> adalah satu atau beberapa pasangan parameter value.

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

gtag('config', 'AW-CONVERSION_ID');

Demikian pula, perintah config dapat digunakan dengan Google Analytics:

gtag('config', 'GA_MEASUREMENT_ID');

Untuk menunjukkan cara mengirim informasi config tambahan, berikut adalah 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', 'GA_MEASUREMENT_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`	UA-XXXXXXXX-Y	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 Google Analytics Universal Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

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', 'UA-XXXXXXXX-Y', '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', {currency: 'USD'});

gtag('get', 'UA-XXXXXXXX-Y', 'currency', (currency) => {
  // Do something with currency value you set earlier.
})

`set`

Memungkinkan Anda menetapkan nilai yang tetap ada di semua panggilan gtag() berikutnya di halaman.

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

<parameter-value-pair> adalah nama kunci dan nilai yang akan tetap ada di seluruh panggilan gtag(). Misalnya, kode di bawah ini menetapkan nilai country ke 'US' dan nilai currency ke 'USD' untuk semua peristiwa berikutnya di halaman:

gtag('set', {
  'country': 'US',
  'currency': 'USD'
});

Penggunaan perintah set berbeda dengan meneruskan nilai langsung ke perintah event. Jika Anda meneruskan nilai langsung ke perintah event, nilai tersebut hanya berlaku untuk peristiwa yang diaktifkan. Namun, dengan set, nilai akan tetap ada di halaman saat ini dan diteruskan dengan semua peristiwa berikutnya. Sebagai gambaran, bandingkan dua contoh berikut:

gtag('event', 'login', {'method': 'Google'});
gtag('event', 'share');

dan

gtag('set', {'method': 'Google'});
gtag('event', 'login');
gtag('event', 'share');

Pada contoh pertama, peristiwa login akan diteruskan dengan nilai method 'Google' dan peristiwa share akan diteruskan tanpa parameter apa pun. Pada contoh kedua, baik login maupun share akan diteruskan dengan nilai method 'Google'.

`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 (yaitu kustom). Misalnya, lihat cara peristiwa kustom digunakan di Google Analytics.

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

`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
`ad_storage`	`'allowed'` \| `'denied'`
`analytics_storage`	`'allowed'` \| `'denied'`
`wait_for_update`	bilangan bulat positif apa pun

Cakupan parameter

Nilai parameter dapat mencakup peristiwa individual, semua peristiwa yang dikirim ke <TARGET_ID> tertentu , atau secara global ke semua peristiwa. Hal ini dimungkinkan dengan menggunakan perintah event, config, dan set.

Parameter value yang ditetapkan dalam satu cakupan tidak mengubah nilai yang ditetapkan untuk parameter yang sama dalam cakupan berbeda. Dalam contoh di bawah, perintah config tidak mengubah nilai global untuk currency yang sebelumnya ditetapkan dengan perintah set. Setelah kedua perintah dijalankan, nilai global currency masih 'EUR'.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// Set currency for <TARGET_ID>
gtag('config','<TARGET_ID>', { 'currency': 'USD' });

Prioritas parameter

Jika nilai yang berbeda ditetapkan ke parameter yang sama dalam cakupan berbeda, hanya satu nilai yang digunakan saat memproses peristiwa. Nilai parameter yang mencakup event akan didahulukan dari parameter yang mencakup config, dan parameter config didahulukan dari parameter cakupan global yang menggunakan set.

// Set global currency to Euros
gtag('set', { 'currency': 'EUR' });

// 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>' });