Riferimento API del tag Google

L'API del tag Google (gtag.js) è composta da una singola funzione, gtag(), con la seguente sintassi:

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

• <command> è uno dei seguenti comandi:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> sono i parametri che puoi passare a gtag(). I parametri del comando variano in base al comando; fai riferimento al riferimento al comando riportato di seguito.

Puoi richiamare i comandi gtag() in qualsiasi punto della pagina, a condizione che i comandi vengano visualizzati sotto lo snippet del tag Google. Per scoprire come aggiungere lo snippet a una pagina, consulta la guida all'installazione.

Ambito dei parametri

Puoi definire l'ambito dei valori dei parametri per singoli eventi, tutti gli eventi inviati a un <TARGET_ID> specifico o a livello globale per tutti gli eventi. Puoi farlo utilizzando i comandi event, config e set.

I valori dei parametri impostati in un ambito non modificano i valori impostati per lo stesso parametro in un ambito diverso. Nell'esempio seguente, il comando config non modifica il valore globale di campaign_id precedentemente assegnato con il comando set. Dopo l'esecuzione di entrambi i comandi, il valore globale di campaign_id è ancora '1234'.

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

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

Precedenza dei parametri

Se allo stesso parametro viene assegnato un valore diverso in ambiti diversi, durante l'elaborazione degli eventi viene utilizzato un solo valore. I valori dei parametri con ambito event avranno la precedenza sui parametri con ambito config, mentre i parametri config hanno la precedenza sui parametri con ambito globale utilizzando 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

Consente di aggiungere ulteriori informazioni di configurazione alle destinazioni. In genere si tratta di una configurazione specifica di un prodotto, ma devi configurarla una sola volta se utilizzi sia Google Ads che Google Analytics.

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

<TARGET_ID> è un identificatore che identifica in modo univoco il target degli hit, ad esempio una proprietà Google Analytics o un account Google Ads. <additional_config_info> corrisponde a una o più coppie parametro-valore.

Questo esempio configura un tag per inviare dati a un account Google Ads:

gtag('config', 'TAG_ID');

dove "TAG_ID" è l'ID tag del tag Google.

Per dimostrare come inviare ulteriori informazioni di configurazione, ecco un esempio che configura un tag per l'invio di dati a un account Analytics con un parametro send_page_view che trasmette il valore false e un parametro groups che trasmette il valore 'agency'.

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

get

Consente di ottenere vari valori da gtag.js, inclusi i valori impostati con il comando set.

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

Argomento	Tipo	Esempio	Descrizione
<target>	string	G-XXXXXXXXXX	Il target da cui recuperare i valori.
<nome_campo>	FieldName	client_id	Il nome del campo da recuperare.
callback	Function	(field) => console.log(field)	Una funzione che verrà richiamata con il campo richiesto oppure undefined se non viene configurato.

FieldName

Il nome del campo può essere il nome di un campo personalizzato impostato con il comando gtag('set') oppure uno dei seguenti valori:

Nome campo	Destinazioni supportate
client_id	Google Analytics 4 Universal Analytics di Google Analytics
session_id	Google Analytics 4
gclid	Google Ads Floodlight

Nota: se utilizzi il comando set con questi nomi dei campi, il valore impostato avrà la precedenza.

Esempi

Trasforma il valore in una promessa

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

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

Invia l'evento a Measurement Protocol

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

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

Ottenere un valore da te impostato

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

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

set

Il comando set consente di definire i parametri che verranno associati a ogni evento successivo sulla pagina.

Nota: ti consigliamo di utilizzare i comandi config o event dove possibile.

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

Ad esempio, puoi condividere i parametri della campagna in modo che siano accessibili da più tag sulla stessa pagina.

L'esempio seguente illustra l'impostazione di un nome e di un ID campagna per un evento di shopping del Black Friday. Poiché hai utilizzato set, tutti gli altri tag, ad esempio i tag evento GA4 o i tag di remarketing di Google Ads, possono accedere a questi dati.

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

event

Utilizza il comando event per inviare i dati degli eventi.

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

<event_name> può essere:

• Un evento consigliato. Ogni evento consigliato può includere parametri consigliati.
• Un evento personalizzato. Un evento personalizzato è un nome di evento arbitrario da te creato, con parametri arbitrari (ovvero personalizzati). Ad esempio, scopri come vengono utilizzati gli eventi personalizzati in Google Analytics.

<event_params> corrisponde a una o più coppie parametro-valore. Ogni coppia separata da una virgola.

Il seguente comando event attiva l'evento consigliato screen_view con due parametri: app_name e screen_name.

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

Importante: lo snippet del tag Google deve apparire nella stessa pagina e sopra i comandi event, altrimenti i dati non verranno inviati.

consent

Usa il comando consent per configurare il consenso.

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

Consulta la sezione relativa al consenso nel Centro assistenza per ulteriori informazioni sul comportamento configurato da questi parametri.

<consent_arg> è uno tra 'default' o 'update'. 'default' viene utilizzato per impostare i parametri di consenso predefiniti da utilizzare, mentre 'update' viene utilizzato per aggiornare questi parametri quando un utente indica il suo consenso.

Sono supportati i seguenti <consent_params>:

Nome campo	Valori consentiti	Descrizione
ad_storage	'granted' | 'denied'	Consente l'archiviazione di cookie (web) o identificatori di dispositivi (app) relativi alla pubblicità.
ad_user_data	'granted' | 'denied'	Imposta il consenso per l'invio dei dati utente a Google per scopi pubblicitari.
ad_personalization	'granted' | 'denied'	Imposta il consenso per la pubblicità personalizzata.
analytics_storage	'granted' | 'denied'	Consente l'archiviazione di cookie (web) o identificatori di app (app) correlati all'analisi, ad esempio la durata della visita.
wait_for_update	qualsiasi numero intero positivo	Imposta il tempo di attesa in millisecondi per una chiamata di aggiornamento del consenso.