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

• <command> è uno dei seguenti comandi:
  • config
  • get
  • set
  • event
  • consent
• <command parameters> sono i parametri che puoi passare a gtag(). I parametri dei comandi variano a seconda del comando; consulta il riferimento ai comandi 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 parametro

Puoi definire l'ambito dei valori dei parametri per singoli eventi, per tutti gli eventi inviati a un <TARGET_ID> specifico 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 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 a uno stesso parametro vengono assegnati valori diversi 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 e 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 informazioni di configurazione aggiuntive ai target. Si tratta in genere 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>});

<TARGET_ID> è un identificatore che identifica in modo univoco la destinazione degli hit, ad esempio una proprietà Google Analytics o un account Google Ads. <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 passa un valore di false e un parametro groups che passa un valore di '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)

FieldName

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

Esempi

Inserire un valore in una promessa

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

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

Inviare 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 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 possano essere accessibili a più tag sulla stessa pagina.

L'esempio riportato di seguito mostra 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 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> è:

• Un evento consigliato. Ogni evento consigliato può accettare parametri consigliati.
• Un evento personalizzato. Un evento personalizzato è un nome di evento arbitrario che inventi, con parametri arbitrari. Per saperne di più, vedi Configurare gli eventi.

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

consent

Utilizza il comando consent per configurare il consenso.

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

Per ulteriori informazioni sul comportamento configurato da questi parametri, consulta la sezione Consenso del Centro assistenza.

<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 una volta che un utente indica il proprio consenso.

Sono supportati i seguenti <consent_params>: