Questa pagina è stata tradotta dall'API Cloud Translation.

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 a seconda del comando; fai riferimento al riferimento per il comando di seguito.

Puoi richiamare i comandi gtag() in qualsiasi punto della pagina, a condizione che 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 limitare i valori dei parametri a singoli eventi, a tutti gli eventi inviati a un <TARGET_ID> specifico o a tutti gli eventi a livello globale. Per farlo, 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 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 vengono assegnati valori diversi in ambiti diversi, viene utilizzato solo un singolo valore durante l'elaborazione degli eventi. I valori dei parametri con ambito event hanno 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 ai target. Si tratta solitamente di una configurazione specifica per un prodotto, ma devi eseguire questa operazione solo una volta se utilizzi sia Google Ads sia Google Analytics.

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

<TARGET_ID> è un identificatore che identifica in modo univoco il target per gli hit, come una proprietà Google Analytics o un account Google Ads. <additional_config_info> è 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 del tag Google.

Per dimostrare come inviare ulteriori informazioni sulla configurazione, ecco un esempio che configura un tag per inviare 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	La destinazione 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 o `undefined` se non è impostato.

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
gclid	Google Ads Floodlight

Esempi

Ottenere un 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 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 siano accessibili a più tag nella stessa pagina.

L'esempio seguente mostra l'impostazione del nome e dell'ID di una 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 sugli 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 arbitrario che puoi creare con parametri arbitrari. Per ulteriori informazioni, consulta Configurare gli eventi.

<event_params> è 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 nel Centro assistenza.

<consent_arg> è 'default' o 'update'. 'default' viene utilizzato per impostare i parametri di consenso predefiniti da utilizzare e 'update' per aggiornarli quando 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 esempio la durata della visita.
`wait_for_update`	qualsiasi numero intero positivo	Imposta un tempo in millisecondi da attendere per una chiamata di aggiornamento del consenso.