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(). Comando variano a seconda del comando; al riferimento ai comandi, di seguito.

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

Ambito dei parametri

Puoi limitare i valori dei parametri a singoli eventi, a tutti gli eventi inviati a un in un determinato <TARGET_ID> o a livello globale per tutti gli eventi. Ciò si ottiene utilizzando i comandi event, config e set.

I valori dei parametri impostati in un ambito non modificano i valori impostati per lo stesso ambito in un ambito diverso. Nell'esempio seguente, il comando config non modificare il valore globale per campaign_id assegnato in precedenza con set . Dopo l'esecuzione di entrambi i comandi, il valore globale di campaign_id viene 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, viene utilizzato un singolo valore per l'elaborazione degli eventi. I valori dei parametri hanno come ambito event avrà la precedenza sui parametri con ambito config e 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 ai target. Questo è di solito una configurazione specifica per un prodotto, ma è sufficiente configura questa opzione una sola volta se utilizzi sia Google Ads sia Google Analytics.

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

<TARGET_ID> è un identificatore univoco del target per gli hit, come una proprietà Google Analytics o un account Google Ads. <additional_config_info> corrisponde a una o più coppie parametro-valore.

In questo esempio viene configurato un tag per inviare dati a un account Google Ads:

gtag('config', 'TAG_ID');

dove "TAG_ID" è l'ID tag per il tag Google.

Ecco un esempio per dimostrare come inviare ulteriori informazioni di configurazione che configura un tag per inviare dati a un account Analytics con un Parametro send_page_view che trasmette il valore false e un groups che trasmette il valore 'agency'.

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

get

Ti consente di ottenere vari valori da gtag.js, inclusi quelli impostati con Comando set.

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

FieldName

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

Esempi

Sfruttare il valore di 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...
}

Ottieni il valore che imposti

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 successivo sulla pagina.

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

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

L'esempio di seguito illustra l'impostazione di un nome e di un ID campagna per un Black Friday di shopping. 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> è:

• Un evento consigliato. Ogni evento consigliato può richiedere parametri consigliati.
• Un evento personalizzato. Un evento personalizzato è un nome di evento arbitrario che crei. con parametri arbitrari (ovvero personalizzati). Ad esempio, vedi come vengono utilizzati gli eventi personalizzati in Google Analytics.

<event_params> corrisponde a una o più coppie parametro-valore. Ogni coppia è separata da un 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'
});

consent

Utilizza il comando consent per configurare il consenso.

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

Per ulteriori informazioni sul comportamento di queste persone, consulta la pagina relativa al consenso nel Centro assistenza e configurare i parametri.

<consent_arg> è uno di 'default' o 'update'. 'default' viene utilizzato per impostare i parametri predefiniti per il consenso da usare e 'update' è utilizzato per aggiornare questi parametri dopo che un utente ha espresso il suo consenso.

Sono supportati i seguenti <consent_params>: