Livello dati

Il livello dati è un oggetto utilizzato da Google Tag Manager e gtag.js per trasferire informazioni ai tag. Gli eventi o le variabili possono essere trasmessi utilizzando il livello dati e gli attivatori possono essere configurati in base ai valori delle variabili.

Ad esempio, se attivi un tag di remarketing quando il valore di purchase_total è superiore a 100 $, o in base a eventi specifici, ad esempio quando viene fatto clic su un pulsante, il livello dati può essere configurato per rendere disponibili i dati ai tag. L'oggetto del livello dati è strutturato come JSON. Ad esempio:

{
  event: "checkout_button",
  gtm: {
    uniqueEventId: 2,
    start: 1639524976560,
    scrollThreshold: 90,
    scrollUnits: "percent",
    scrollDirection: "vertical",
    triggers: "1_27"
  },
  value: "120"
}

I tag Google sono progettati per fare riferimento alle informazioni aggiunte al livello dati in modo organizzato e prevedibile, anziché analizzando variabili, informazioni sulle transazioni, categorie di pagine e altri indicatori sparsi nella pagina. Un'implementazione del livello dati compilata con variabili e valori associati contribuirà a garantire che i dati pertinenti siano disponibili quando i tag ne hanno bisogno.

Installazione

Per le installazioni di pagine web di Tag Manager, devi creare un livello dati. Il seguente esempio di codice mostra dove viene stabilito il livello dati, prima del caricamento di Tag Manager.

<script>
window.dataLayer = window.dataLayer || [];
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Nelle implementazioni standard di gtag.js in cui il tag è stato copiato dal prodotto e aggiunto a una pagina web, viene fornito il codice per stabilire il livello dati. Nelle implementazioni personalizzate del tag Google, aggiungi il codice del livello dati all'inizio dello script, come mostrato nel seguente esempio di codice:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'TAG_ID');
</script>

Come vengono elaborate le informazioni del livello dati

Quando viene caricato un contenitore, Tag Manager inizia a elaborare tutti i messaggi push del livello dati in coda. Tag Manager elabora i messaggi in base all'ordine di ricezione: ogni messaggio viene elaborato uno alla volta, nell'ordine in cui è stato ricevuto. Se il messaggio è un evento, tutti i tag con condizioni di attivazione soddisfatte verranno attivati prima che Tag Manager passi al messaggio successivo.

Se viene effettuata una chiamata gtag() o dataLayer.push() tramite il codice su una pagina, in un modello personalizzato o in un tag HTML personalizzato, il messaggio associato viene messo in coda ed elaborato dopo che tutti gli altri messaggi in attesa sono stati valutati. Ciò significa che non è garantita la disponibilità di valori del livello dati aggiornati per l'evento successivo. Per gestire questi casi, devi aggiungere il nome di un evento a un messaggio quando viene inviato al livello dati, poi ascoltare tale nome con un attivatore di evento personalizzato.

Importante: non utilizzare i tag HTML personalizzati per implementare il codice basato su gtag.js. Utilizza invece i modelli di tag nativi di Tag Manager per Google Ads, Analytics e Floodlight.

Importante: non utilizzare tag HTML personalizzati per configurare le impostazioni per il consenso in Tag Manager. Poiché le impostazioni per il consenso devono essere applicate prima dell'attivazione dei tag pertinenti in un contenitore Tag Manager, devi applicare le API Tag Manager Consent per configurare il comportamento predefinito e di aggiornamento. Utilizza le API per il consenso di Tag Manager per assicurarti che gli aggiornamenti del consenso vengano elaborati prima di qualsiasi elemento in coda nel livello dati, in modo che tutti i tag attivati dallo stesso evento visualizzino lo stesso stato del consenso.

Punto chiave: puoi utilizzare Google Tag Assistant per esaminare lo stato del livello dati in qualsiasi punto di una catena di eventi.

Utilizzare un livello dati con i gestori di eventi

L'oggetto dataLayer utilizza un comando event per avviare l'invio di eventi.

Il tag Google e Tag Manager utilizzano una variabile del livello dati speciale chiamata event che viene utilizzata dai listener di eventi JavaScript per attivare i tag quando un utente interagisce con gli elementi del sito web. Ad esempio, potresti voler attivare un tag di monitoraggio delle conversioni quando un utente fa clic su un pulsante di conferma dell'acquisto. Gli eventi possono essere chiamati ogni volta che un utente interagisce con elementi del sito web come link, pulsanti, scorrimenti e così via.

Questa funzionalità viene implementata chiamando dataLayer.push() quando si verifica un evento. La sintassi per inviare un evento con dataLayer.push() è la seguente:

dataLayer.push({'event': 'event_name'});

Dove event_name è una stringa che descrive l'evento, ad esempio 'login', 'purchase' o 'search'.

Utilizza dataLayer.push() per inviare i dati sugli eventi quando si verifica un'azione che vuoi misurare. Ad esempio, per inviare un evento quando un utente fa clic su un pulsante, modifica il gestore onclick del pulsante per chiamare dataLayer.push():

<button onclick="dataLayer.push({'event': 'login'});">Button 1</button>

Puoi inserire dinamicamente le variabili del livello dati nel livello dati per acquisire informazioni come i valori inseriti o selezionati in un modulo, i metadati associati a un video riprodotto dal visitatore, il colore di un prodotto (ad esempio un'auto) personalizzato dal visitatore, gli URL di destinazione dei link su cui è stato fatto clic e così via.

Come per gli eventi, questa funzionalità viene implementata chiamando l'API push() per aggiungere o sostituire le variabili del livello dati nel livello dati. La sintassi di base per impostare le variabili di livello dati dinamiche è la seguente:

dataLayer.push({'variable_name': 'variable_value'});

Dove 'variable_name' è una stringa che indica il nome della variabile livello dati da impostare e 'variable_value' è una stringa che indica il valore della variabile livello dati da impostare o sostituire.

Ad esempio, per impostare una variabile di livello dati con una preferenza di colore quando un visitatore interagisce con uno strumento di personalizzazione del prodotto, puoi inserire la seguente variabile di livello dati dinamica:

dataLayer.push({'color': 'red'});

Un push, più variabili

Puoi inviare più variabili ed eventi contemporaneamente:

dataLayer.push({
  'color': 'red',
  'conversionValue': 50,
  'event': 'customize'
});

Importante :se inserisci un push di una variabile con lo stesso nome di una variabile esistente nel data layer, il valore esistente verrà sovrascritto dal nuovo valore.

Rendere persistenti le variabili di livello dati

Per rendere persistenti le variabili di livello dati tra le pagine web, chiama dataLayer.push() dopo che il livello dati è stato istanziato a ogni caricamento della pagina e inserisci le variabili nel livello dati. Se vuoi che queste variabili del livello dati siano disponibili per Tag Manager quando il contenitore viene caricato, aggiungi una chiamata dataLayer.push() sopra il codice del contenitore di Tag Manager, come mostrato nell'esempio seguente:

<script>
window.dataLayer = window.dataLayer || [];

dataLayer.push({
  'event': 'Pageview',
  'pagePath': 'https://www.googleanalytics.dev/pancakes',
  'pageTitle': 'Pancake Event Signup',
  'visitorType': 'customer'
});
</script>
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Ogni variabile dichiarata all'interno dell'oggetto livello dati viene mantenuta solo finché il visitatore rimane sulla pagina corrente. Le variabili di livello dati pertinenti su più pagine (ad esempio, visitorType) devono essere dichiarate nel livello dati di ogni pagina del tuo sito web. Anche se non è necessario inserire lo stesso insieme di variabili nel data layer in ogni pagina, devi utilizzare una convenzione di denominazione coerente. In altre parole, se imposti la categoria di pagina nella pagina di registrazione utilizzando una variabile chiamata pageCategory, anche le pagine di prodotto e di acquisto devono utilizzare la variabile pageCategory.

Risoluzione dei problemi

Ecco alcuni suggerimenti per la risoluzione dei problemi relativi al livello dati:

Non sovrascrivere la variabile window.dataLayer:quando utilizzi direttamente il livello dati (ad esempio dataLayer = [{'item': 'value'}]), sovrascriverà tutti i valori esistenti in dataLayer. Le installazioni di Tag Manager devono istanziare il livello dati il più in alto possibile nel codice sorgente, sopra lo snippet contenitore, utilizzando window.dataLayer = window.dataLayer || [];. Dopo aver dichiarato dataLayer, utilizza dataLayer.push({'item': 'value'}) per aggiungere altri valori. Se questi valori devono essere disponibili per Tag Manager al caricamento della pagina, anche la chiamata dataLayer.push() deve essere sopra il codice del contenitore Tag Manager.

Il nome dell'oggetto dataLayer è sensibile alle maiuscole e minuscole:se provi a eseguire il push di una variabile o di un evento senza il formato corretto, l'operazione non andrà a buon fine.

datalayer.push({'pageTitle': 'Home'});    // Bad (datalayer in lowercase)
dataLayer.push({'pageTitle': 'Home'});    // Good (dataLayer in camel case)

dataLayer.push deve essere chiamato con oggetti JavaScript validi. Tutti i nomi delle variabili del data layer devono essere racchiusi tra virgolette.

dataLayer.push({new-variable: 'value'});      // Bad - no quote marks
dataLayer.push({'new-variable': 'value'});    // Good - proper quote marks

Mantieni la coerenza dei nomi delle variabili nelle diverse pagine:se utilizzi nomi di variabili diversi per lo stesso concetto in pagine diverse, i tag non potranno attivarsi in modo coerente in tutte le posizioni previste.

Non valido:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitor_type': 'high-value'});

Valido:

// Homepage:
dataLayer.push({'visitorType': 'low-value'});

// Checkout Page:
dataLayer.push({'visitorType': 'high-value'});

Rinomina il livello dati

Il nome predefinito dell'oggetto del livello dati avviato dal tag Google o da Tag Manager è dataLayer. Se preferisci utilizzare un nome diverso per il tuo livello dati, puoi farlo modificando il valore parametro nel tuo tag Google o nello snippet contenitore di Tag Manager con il nome che preferisci.

gtag.js

Aggiungi un parametro di ricerca denominato "l" all'URL per impostare il nuovo nome del data layer, ad esempio l=myNewName. Aggiorna tutte le istanze di dataLayer nello snippet del tag Google con il nuovo nome.

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID&l=myNewName"></script>
<script>
  window.myNewName = window.myNewName || [];
  function gtag(){myNewName.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'TAG_ID');
</script>

Tag Manager

Sostituisci il valore parametro del livello dati (evidenziato di seguito) nello snippet contenitore con il nome che preferisci.

Importante: non sostituire il valore parametro non evidenziato.

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','myNewName','GTM-XXXXXX');</script>
<!-- End Google Tag Manager -->

Una volta rinominato, tutti i riferimenti al livello dati (ad es. quando dichiari il livello dati sopra lo snippet o quando inserisci eventi o variabili del livello dati dinamico nel livello dati con il comando .push()) devono essere modificati in modo da riflettere il nome personalizzato del livello dati:

<script>
  window.myNewName = window.myNewName || [];
  window.myNewName.push({'variable_name': 'variable_value'});
</script>

Importante: utilizza un solo livello dati per pagina

È supportato un solo oggetto dataLayer per pagina. Google Tag Manager e gtag.js si basano su un singolo array JavaScript globale denominato window.dataLayer per ricevere, mettere in coda ed elaborare tutti gli eventi e le variabili nell'ordine in cui vengono aggiunti. Gli snippet del contenitore collegano i propri listener e la logica di elaborazione in modo specifico a questo singolo array. Il tentativo di utilizzare più di un'istanza del data layer o di reinizializzare in modo errato il data layer (ad esempio, sovrascrivendolo con window.dataLayer = [] dopo il caricamento di GTM) può causare problemi significativi:

• I tag potrebbero non attivarsi:gli eventi e le variabili inviati a un'istanza di dataLayer che Google Tag Manager o il tag Google non monitorano attivamente non attiveranno i tag.
• Raccolta di dati incoerente: diverse parti della pagina o diversi script potrebbero inviare dati a array dataLayer separati e isolati, il che comporta che le informazioni incomplete o errate raggiungano i tag di analisi e marketing.
• Perdita di dati:le informazioni destinate al monitoraggio potrebbero andare perse se inviate all'istanza dataLayer errata.
• Difficoltà di debug:è difficile diagnosticare i problemi di tagging poiché il flusso di dati di monitoraggio è imprevedibile.

Best practice: esegui sempre l'istanza del data layer utilizzando window.dataLayer = window.dataLayer || []; una volta per pagina, in genere nella parte superiore del <head> della pagina, prima dello snippet GTM o gtag.js. Utilizza sempre dataLayer.push() per aggiungere eventi o variabili successivi. Non sovrascrivere o riassegnare mai la variabile window.dataLayer.

Metodi personalizzati del livello dati

Se inserisci una funzione nel data layer, verrà richiamata con this impostato su un modello di dati astratto. Questo modello di dati astratto può ottenere e impostare valori in un archivio chiave-valore e fornisce anche un modo per reimpostare il data layer.

Importante :per utilizzare metodi del livello dati personalizzati, devi utilizzare .push per inviare i dati direttamente alla variabile dataLayer. Se utilizzi gtag, la funzione verrà interpretata come un comando non valido e ignorata.

imposta

La funzione set nel modello di dati astratto consente di impostare i valori da recuperare tramite get.

window.dataLayer.push(function() {
  this.set('time', new Date());
});

get

La funzione get nel modello di dati astratto consente di recuperare i valori che sono stati impostati.

window.dataLayer.push(function() {
  const existingTime = this.get('time');
  if (existingTime !== null) {
    // Change behavior based on whether or not this value exists...
  } else {
    // ...
  }
});

reimposta

La funzione reset sul modello di dati astratto consente di reimpostare i dati nel livello dati. Questa opzione è più utile con una pagina che rimarrà aperta e le dimensioni del livello di dati continuano a crescere nel tempo. Per reimpostare il livello dati, utilizza il seguente codice:

window.dataLayer.push(function() {
  this.reset();
});