Riferimento API del tag Google

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

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

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

Ambito del parametro

Puoi applicare l'ambito dei valori dei parametri a singoli eventi, a tutti gli eventi inviati a un <TARGET_ID> specifico o a livello globale a tutti gli eventi. A questo scopo, utilizza 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 assegnato in precedenza 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 vengono assegnati valori diversi in ambiti diversi, durante l'elaborazione degli eventi viene utilizzato un solo valore. I valori parametro con ambito event avranno la precedenza sui parametri con ambito config, mentre i parametri config avranno la precedenza sui parametri con ambito globale che utilizzano 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 ai target. In genere, si tratta di una configurazione specifica per un prodotto, ma devi configurarla una sola volta se utilizzi sia Google Ads che Google Analytics.

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

Punti chiave su <TARGET_ID>:

  • <TARGET_ID> nel comando gtag('config', <TARGET_ID>, ...) è un ID tag che identifica dove gtag.js deve inviare i dati sugli eventi. Può trattarsi di una destinazione come una proprietà Google Analytics, un account Google Ads, una configurazione Floodlight o un tag Google con più destinazioni.

  • Un ID tag, ad esempio GT-XXXXXX, G-XXXXXX o AW-YYYYYY, è un identificatore del tag Google. Aggiungi questo ID al codice del tuo sito web per caricare il tag Google.

  • Un singolo tag Google (identificato dal relativo ID tag) può essere configurato per inviare dati a più destinazioni. Sebbene alcuni ID tag possano sembrare identici agli ID destinazione, ad esempio G-XXXXXX per una proprietà Google Analytics o AW-YYYYYY per un account Google Ads, <TARGET_ID> nel comando config si riferisce all'istanza specifica del tag Google caricato nella pagina.

  • Il comando gtag('config', ...) configura il comportamento del tag Google associato a quel <TARGET_ID> specifico. Sebbene l'ID tag incluso nello script src carichi in genere il tag Google, puoi utilizzare qualsiasi ID tag valido associato al tuo account nel comando gtag('config').

  • A un singolo tag Google possono essere associati più ID tag, spesso a causa dell'unione dei tag. Qualsiasi ID associato può essere utilizzato nel parametro src dello script per caricare il tag Google.

  • Se invii dati a più destinazioni o utilizzi più tag, devi includere un solo snippet del tag Google con un ID tag nello script src. Poi, includi un comando gtag('config') per ogni ID tag o destinazione aggiuntivi.

<additional_config_info> rappresenta 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 mostrare come inviare informazioni di configurazione aggiuntive, ecco un esempio che configura un tag per inviare dati a un account Analytics con un parametro send_page_view che trasmette un valore false e un parametro groups che trasmette un valore 'agency'.

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

get

Ti 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.
<field_name> FieldName client_id Il nome del campo da ottenere.
callback Function (field) => console.log(field)

Una funzione che verrà richiamata con il campo richiesto o indicata come undefined se non è impostata.

FieldName

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

Nome campo Target supportati
client_id
  • Google Analytics 4
session_id
  • Google Analytics 4
session_number
  • Google Analytics 4
gclid
  • Google Ads
  • Floodlight

Esempi

Inserisci il valore in una Promise 

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 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 ti consente di definire i parametri che verranno associati a ogni evento successivo nella pagina.

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

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

L'esempio seguente illustra l'impostazione di un nome e di un ID campagna per un evento di acquisto 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 sugli eventi.

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

<event_name> è:

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

Utilizza il comando consent per configurare il consenso.

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

Per saperne di più sul comportamento configurato da questi parametri, consulta la sezione sul consenso nel Centro assistenza.

<consent_arg> è 'default' o 'update'. 'default' viene utilizzato per impostare i parametri di consenso predefiniti da utilizzare, mentre 'update' viene utilizzato per aggiornare questi parametri una volta che un utente indica il proprio consenso.

Sono supportati i seguenti <consent_params>:

Nome campo Valori consentiti Descrizione
ad_storage 'granted' | 'denied' Consente l'archiviazione di informazioni, come i cookie (web) o gli identificatori dei dispositivi (app), correlate 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 informazioni, come i cookie (web) o gli identificatori di app (app), correlate all'analisi (ad es. la durata della visita).
wait_for_update qualsiasi numero intero positivo Imposta un tempo in millisecondi di attesa per una chiamata di aggiornamento del consenso.