Come creare un tag del server

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

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:

  1. Configurazione totale: aggiungi un campo di configurazione per ogni parametro. Richiedi all'utente di impostare tutto esplicitamente.
  2. Nessuna configurazione: non sono disponibili opzioni per configurare il tag. Tutti i dati vengono recuperati direttamente dall'evento.
  3. 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 parametro event_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 parametro page_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 parametro u 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'API setCookie per impostare il cookie. Ciò significa che il tag Baz Analytics è l'unica cosa che sa dove e come viene archiviato il cookie. Come l, il parametro u deve essere raccolto automaticamente.

Dopo aver impostato la configurazione del tag, il codice dovrebbe avere il seguente aspetto:

Istantanea della configurazione del tag Baz Analytics.

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:

  1. Recupera il nome dell'evento dalla configurazione del tag.
  2. Recupera l'URL della pagina dalla proprietà page_location dell'evento.
  3. 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.
  4. 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 e page_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.

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.