In Un'introduzione al tagging lato server, troverai una panoramica del tagging lato server in Tag Manager. Hai imparato cosa sono i client e cosa fanno: i client ricevono i dati sugli eventi dai dispositivi degli utenti e li adattano per l'utilizzo da parte del resto del container. Questo articolo descrive come elaborare i dati nei tag lato server.
In un contenitore del server, i tag ricevono i dati sugli eventi in arrivo dai client, li trasformano e li inviano nuovamente per la raccolta e l'analisi. I tag possono inviare i dati dove vuoi. Se la destinazione accetta richieste HTTP, può anche accettare i dati da un contenitore del server.
I contenitori del server hanno tre tag integrati pronti per essere utilizzati senza configurazioni personalizzate:
- Google Analytics 4
- Google Analytics: Universal Analytics
- Richiesta HTTP
Se vuoi inviare i dati a una destinazione diversa da Google Analytics o se hai bisogno di più funzionalità rispetto a quelle fornite dal tag di richiesta HTTP, devi utilizzare un tag diverso. Puoi trovare ulteriori tag nella Galleria modelli della community oppure puoi scriverne di nuovi. Questo tutorial illustra le nozioni di base della scrittura di tag personalizzati per un contenitore del server.
Obiettivi
- Scopri quali API utilizzare per leggere i dati degli eventi, inviare richieste HTTP e impostare i cookie nel browser.
- Scopri le best practice per la progettazione delle opzioni di configurazione del tag.
- Scopri la differenza tra i dati specificati dagli utenti e i dati raccolti automaticamente e perché questa distinzione è importante.
- Scopri il ruolo di un tag in un contenitore del server. Comprendi cosa deve e non deve fare un tag.
- Scopri quando valutare l'opportunità di inviare un modello di tag alla Galleria modelli della community.
Prerequisiti
- Un container del server di cui è stato eseguito il deployment
- Familiarità con Tag Manager, container del server e i relativi concetti di base come client, tag, attivatori e variabili
- Familiarità con le nozioni di base della scrittura di modelli per tag e variabili
Tag Baz Analytics
In questo tutorial creerai un tag che invia dati di misurazione a un servizio chiamato Baz Analytics.
Baz Analytics è un semplice servizio di analisi ipotetico che importa i dati tramite richieste HTTP GET a https://example.com/baz_analytics
. Dispone dei seguenti parametri:
Parametro | Esempio | Descrizione |
---|---|---|
id | BA-1234 | L'ID del tuo account Baz Analytics. |
inglese | click | Nome evento. |
l | https://www.google.com/search?q=sgtm
|
URL della pagina in cui si è verificato l'evento. |
u | 2384294892 | L'ID dell'utente che esegue l'azione. Utilizzato per ricollegare più azioni a un singolo utente. |
Configurazione dei tag
La prima cosa da fare è creare il modello di tag. Vai alla sezione Modelli del contenitore e fai clic su Nuovo nella sezione Modelli di tag. Aggiungi un nome e una descrizione al tag.
Poi, vai alla sezione Campi dell'editor del modello per aggiungere le diverse opzioni di configurazione per il tag. La domanda successiva è: di quali opzioni hai bisogno? Esistono tre modi per creare il tag:
- Configurazione totale: aggiungi un campo di configurazione per ogni parametro. Richiedi all'utente di impostare tutto esplicitamente.
- Nessuna configurazione: non sono disponibili opzioni per configurare il tag. Tutti i dati vengono recuperati direttamente dall'evento.
- Alcune configurazioni: avere i campi per alcuni parametri e non per altri.
La presenza di campi per ogni parametro è molto flessibile e offre all'utente il controllo totale sulla configurazione dei tag. In pratica, però, questo di solito comporta
molto lavoro duplicato. In particolare, elementi come il parametro l
di Baz Analytics, che contiene l'URL della pagina, sono inequivocabili e universali.
È preferibile che al computer venga inserito lo stesso dato non modificabile ogni volta che viene configurato il tag.
Ad esempio, utilizzare un tag che prende solo i dati da un evento. Questo è il tag più semplice da configurare per un utente, dato che non deve fare nulla. D'altra parte, è anche l'opzione più restrittiva e fragile. Gli utenti non possono modificare il comportamento del tag anche se necessario.
Ad esempio, potrebbero chiamare un evento purchase
sul sito web e in Google
Analytics, ma Baz Analytics lo chiama buy
. Oppure le ipotesi che il tag fa sulla struttura dei dati sugli eventi in arrivo non corrispondono effettivamente alla realtà. In entrambi i casi, l'utente è bloccato.
Come per molte cose, la risposta sta da qualche parte tra i due estremi. È opportuno prendere sempre alcuni dati dall'evento. Gli altri dati devono essere configurati dall'utente. Come fai a decidere quale? Per rispondere a questa domanda, dovremo analizzare più da vicino i dati che arrivano nel container.
Da dove provengono i dati?
I dati che arrivano in un contenitore del server dal tag Google Analytics 4 possono essere approssimativamente divisi in due categorie: dati specificati dall'utente e dati raccolti automaticamente.
I dati specificati dall'utente sono tutto ciò che un utente inserisce in un comando event
di gtag.js. Ad esempio, un comando come questo:
gtag('event', 'search', {
search_term: 'beets',
});
Nel contenitore del server verranno generati i seguenti parametri:
{
event_name: 'search',
search_term: 'beets',
}
È abbastanza semplice, ma dal punto di vista del tag è molto
difficile da utilizzare. Poiché questi dati vengono inseriti dall'utente, possono essere qualsiasi cosa.
Forse, come spiegato in precedenza, l'utente invia solo
eventi consigliati e parametri, ma non è previsto
che lo faccia. Fatta eccezione per la località
(ma non il valore!) del parametro event_name
, non vi sono garanzie
per il formato o la struttura dei dati dell'utente.
Fortunatamente, i dati inseriti dall'utente non sono l'unica cosa che il container riceverà. Riceverà inoltre una serie di dati raccolti automaticamente dal tag Google Analytics 4 nel browser. tra cui ad esempio:
ip_override
language
page_location
page_referrer
page_title
screen_resolution
user_agent
Inoltre, se la richiesta al server proviene da un browser web, potrebbero essere disponibili anche dati dei cookie del browser tramite l'API getCookieValue
.
Insieme, questi elementi costituiscono i dati raccolti automaticamente di cui sopra. In generale, sono dati universalmente e semanticamente non ambigui. Quando una richiesta proviene da un tag GA4 nel browser, questi dati saranno sempre disponibili e avranno sempre lo stesso formato. Per ulteriori dettagli su questi parametri, consulta la documentazione di riferimento sugli eventi.
Questa classificazione ci offre uno strumento utile da utilizzare per decidere quali dati devono essere configurati dall'utente e quali specificare nel tag. I dati raccolti automaticamente possono essere letti direttamente dall'evento. Tutto il resto deve essere configurato dall'utente.
Tenendo conto di questo, dai un'altra occhiata ai parametri del tag Baz Analytics.
- ID misurazione,
id
: poiché non viene raccolto automaticamente, è un chiaro esempio di un valore che l'utente deve inserire durante la configurazione del tag. - Nome dell'evento,
en
: come menzionato sopra, il nome dell'evento può sempre essere preso direttamente dal parametroevent_name
. Tuttavia, poiché il suo valore è definito dall'utente, ti consigliamo di offrire la possibilità di sostituire il nome, se necessario. - URL pagina,
l
: questo valore può essere recuperato dal parametropage_location
, che viene raccolto automaticamente dal tag del browser GA4 di Google Analytics a ogni evento. Pertanto, non devi richiedere all'utente di inserire manualmente un valore. - ID utente,
u
: nel tag del server Baz Analytics, il parametrou
non viene specificato dall'utente né raccolto automaticamente dal tag nella pagina. Viene invece memorizzato in un cookie del browser in modo che gli utenti possano essere identificati durante più visite al sito web. Come vedrai nell'implementazione riportata di seguito, è il tag del server Baz Analytics che utilizza l'APIsetCookie
per impostare il cookie. Ciò significa che il tag Baz Analytics è l'unica cosa che sa dove e come viene archiviato il cookie. Comel
, il parametrou
deve essere raccolto automaticamente.
Dopo aver impostato la configurazione del tag, il codice dovrebbe avere il seguente aspetto:
Implementazione dei tag
Ora che la configurazione del tag è stata rimossa, puoi passare all'implementazione del suo comportamento in JavaScript con sandbox.
Il tag deve svolgere quattro operazioni:
- Recupera il nome dell'evento dalla configurazione del tag.
- Recupera l'URL della pagina dalla proprietà
page_location
dell'evento. - Calcolare un ID utente. Il tag cercherà lo User-ID in un cookie chiamato
_bauid
. Se questo cookie non è presente, il tag calcolerà un nuovo valore e lo memorizzerà per richieste successive. - Crea un URL e invia una richiesta al server di raccolta di Baz Analytics.
Inoltre, è utile pensare a come il tag si inserisce nel contenitore nel suo complesso. Poiché i vari componenti del contenitore svolgono ruoli diversi, il tag non deve eseguire o meno altre operazioni. Il tuo tag:
- Non devono esaminare l'evento per capire se deve essere eseguito. Ecco a cosa serve un attivatore.
- Non deve eseguire il container con l'API
runContainer
. Questo è il compito del cliente. - Con l'importante eccezione dei cookie, non deve provare a interagire direttamente con la richiesta o la risposta. Questo è anche compito del cliente.
Se scrivi un modello di tag che esegue una di queste operazioni, gli utenti del tag potrebbero avere un comportamento poco chiaro. Ad esempio, un tag che invia una risposta alla richiesta in arrivo impedirebbe al client di fare lo stesso. In questo modo, gli utenti non dovrebbero avere le aspettative degli utenti sul comportamento previsto del container.
Tenendo conto di tutto ciò, di seguito è riportata un'implementazione annotata del tag in JavaScript con sandbox.
const encodeUriComponent = require('encodeUriComponent');
const generateRandom = require('generateRandom');
const getCookieValues = require('getCookieValues');
const getEventData = require('getEventData');
const logToConsole = require('logToConsole');
const makeString = require('makeString');
const sendHttpGet = require('sendHttpGet');
const setCookie = require('setCookie');
const USER_ID_COOKIE = '_bauid';
const MAX_USER_ID = 1000000000;
// The event name is taken from either the tag's configuration or from the
// event. Configuration data comes into the sandboxed code as a predefined
// variable called 'data'.
const eventName = data.eventName || getEventData('event_name');
// page_location is automatically collected by the Google Analytics 4 tag.
// Therefore, it's safe to take it directly from event data rather than require
// the user to specify it. Use the getEventData API to retrieve a single data
// point from the event. There's also a getAllEventData API that returns the
// entire event.
const pageLocation = getEventData('page_location');
const userId = getUserId();
const url = 'https://www.example.com/baz_analytics?' +
'id=' + encodeUriComponent(data.measurementId) +
'en=' + encodeUriComponent(eventName) +
(pageLocation ? 'l=' + encodeUriComponent(pageLocation) : '') +
'u=' + userId;
// The sendHttpGet API takes a URL and returns a promise that resolves with the
// result once the request completes. You must call data.gtmOnSuccess() or
// data.gtmOnFailure() so that the container knows when the tag has finished
// executing.
sendHttpGet(url).then((result) => {
if (result.statusCode >= 200 && result.statusCode < 300) {
data.gtmOnSuccess();
} else {
data.gtmOnFailure();
}
});
// The user ID is taken from a cookie, if present. If it's not present, a new ID
// is randomly generated and stored for later use.
//
// Generally speaking, tags should not interact directly with the request or
// response. This prevents different tags from conflicting with each other.
// Cookies, however, are an exception. Tags are the only container entities that
// know which cookies they need to read or write. Therefore, it's okay for tags
// to interact with them directly.
function getUserId() {
const userId = getCookieValues(USER_ID_COOKIE)[0] || generateRandom(0, MAX_USER_ID);
// The setCookie API adds a value to the 'cookie' header on the response.
setCookie(USER_ID_COOKIE, makeString(userId), {
'max-age': 3600 * 24 * 365 * 2,
domain: 'auto',
path: '/',
httpOnly: true,
secure: true,
});
return userId;
}
In questo modo, il tag viene implementato. Prima di poter utilizzare il tag, devi impostare correttamente le relative autorizzazioni API. Vai alla scheda Autorizzazioni dell'Editor modelli e specifica le seguenti autorizzazioni:
- Legge i valori dei cookie:
_bauid
- Legge i dati degli eventi:
event_name
epage_location
- Invia richieste HTTP:
https://www.example.com/*
- Imposta un cookie:
_bauid
È consigliabile inoltre scrivere test per il tag. Per saperne di più sui test dei modelli, leggi la sezione relativa ai test della guida per gli sviluppatori dei modelli.
Infine, ricordati di provare a eseguire il tag con il pulsante Esegui codice almeno una volta. In questo modo, eviterai che molti semplici errori lo commettano sul tuo server.
Inviare il tag alla Galleria modelli della community
Poiché hai svolto tutte le attività di creazione, test e deployment di un nuovo tag, non c'è motivo di tenerlo per te. Se ritieni che il nuovo tag possa essere utile ad altre persone, puoi inviarlo alla Galleria modelli della community.
Conclusione
In questo tutorial hai appreso le nozioni di base sulla scrittura di un tag per un container del server. Hai imparato a:
- API da utilizzare per leggere i dati degli eventi, inviare richieste HTTP e impostare i cookie nel browser.
- Best practice per la progettazione delle opzioni di configurazione di un tag.
- La differenza tra i dati specificati dall'utente e i dati raccolti automaticamente e perché questa distinzione è importante.
- Il ruolo di un tag nel contenitore: cosa deve e cosa non deve fare.
- Quando e come inviare i modelli di tag alla Galleria modelli della community.