Come creare un tag del server

In Introduzione al tagging lato server, hai trovato una panoramica del tagging lato server in Tag Manager. Hai scoperto cosa sono i client e cosa fanno: i client ricevono i dati degli eventi dai dispositivi degli utenti e li adattano per l'utilizzo da parte del resto del contenitore. Questo articolo descrive come elaborare questi dati nei tag lato server.

In un contenitore del server, i tag ricevono i dati degli eventi in entrata dai client, li trasformano e li inviano di nuovo per la raccolta e l'analisi. I tag possono inviare i dati ovunque tu voglia. Se la destinazione accetta le richieste HTTP, può accettare anche i dati da un contenitore del server.

I contenitori del server hanno tre tag integrati pronti per l'uso senza configurazione personalizzata:

• Google Analytics
• Richiesta HTTP

Se vuoi inviare i dati a una destinazione diversa da Google Analytics o hai bisogno di più funzionalità di quelle fornite dal tag Richiesta HTTP, dovrai utilizzare un tag diverso. Puoi trovare altri tag nella Galleria modelli della community o puoi scriverne di tuoi. Questo tutorial ti insegnerà le nozioni di base per scrivere i tuoi tag 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 dall'utente e i dati raccolti automaticamente e perché questa distinzione è importante.
• Scopri il ruolo di un tag in un contenitore del server. Scopri cosa deve e cosa non deve fare un tag.
• Scopri quando prendere in considerazione l'invio di un modello di tag alla Galleria modelli della community.

Prerequisiti

• Un contenitore del server di cui è stato eseguito il deployment
• Familiarità con Tag Manager, i contenitori del server, e i relativi concetti di base come client, tag, attivatori, e variabili
• Familiarità con le nozioni di base per la scrittura di modelli per tag e variabili

Il tag Baz Analytics

In questo tutorial creerai un tag che invia i dati di misurazione a un servizio chiamato Baz Analytics.

Baz Analytics è un servizio di analisi semplice e ipotetico che acquisisce i dati tramite richieste HTTP GET a https://example.com/baz_analytics. Ha i seguenti parametri:

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 di modelli per aggiungere le diverse opzioni di configurazione del 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 in modo esplicito.
2. Nessuna configurazione: non avere opzioni per la configurazione del tag. Tutti i dati vengono presi direttamente dall'evento.
3. Alcune configurazioni: avere campi per alcuni parametri e non per altri.

Avere campi per ogni parametro è molto flessibile e offre all'utente il controllo totale sulla configurazione del tag. In pratica, però, questo di solito comporta un sacco di lavoro duplicato. In particolare, elementi come il parametro l di Baz Analytics, che contiene l'URL della pagina, sono univoci e universali. L'inserimento dello stesso dato invariabile ogni volta che il tag viene configurato è qualcosa che è meglio lasciare al computer.

Forse la risposta è avere un tag che prende i dati solo da un evento. Questo è il tag più semplice possibile da configurare per un utente, poiché 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 ne hanno bisogno. Ad esempio, potrebbero chiamare un evento purchase sul loro sito web e in Google Analytics, ma Baz Analytics lo chiama buy. In alternativa, le ipotesi che il tag fa sulla struttura dei dati degli eventi in entrata potrebbero non corrispondere alla realtà. In entrambi i casi, l'utente è bloccato.

Come per molte cose, la risposta si trova a metà strada tra i due estremi. Alcuni dati hanno senso di essere sempre presi dall'evento. Altri dati devono essere configurati dall'utente. Come si decide quali sono quali? Per rispondere a questa domanda, dobbiamo esaminare più da vicino i dati in entrata nel contenitore.

Da dove provengono i dati?

I dati in entrata in un contenitore del server dal tag Google Analytics possono essere suddivisi approssimativamente 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 gtag.js. Ad esempio, un comando come questo:

gtag('event', 'search', {
  search_term: 'beets',
});

Genererà i seguenti parametri nel contenitore del server:

{
  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 sopra, l'utente invia solo eventi e parametri consigliati, ma non è obbligatorio. Con l'importante eccezione della posizione (ma non del valore!) del parametro event_name, non ci sono garanzie sulla forma o sulla struttura dei dati dell'utente.

Fortunatamente, i dati inseriti dall'utente non sono l'unica cosa che il contenitore riceverà. Riceverà anche una serie di dati raccolti automaticamente dal tag Google Analytics nel browser. tra cui ad esempio:

• ip_override
• language
• page_location
• page_referrer
• page_title
• screen_resolution
• user_agent

Inoltre, se la richiesta del server proviene da un browser web, potrebbero essere disponibili anche i dati dei cookie del browser tramite l'API getCookieValue.

Insieme, questi costituiscono i dati raccolti automaticamente che abbiamo menzionato sopra. In generale, si tratta di dati universali e semanticamente non ambigui. Quando arriva una richiesta da un tag Google Analytics nel browser, questi dati saranno sempre disponibili e avranno sempre lo stesso formato. Per maggiori dettagli su questi parametri, consulta la documentazione di riferimento sugli eventi.

Questa classificazione ci fornisce uno strumento utile da utilizzare per decidere quali dati devono essere configurati dall'utente e quali dati devono essere specificati nel tag. I dati raccolti automaticamente possono essere letti direttamente dall'evento. Tutto il resto deve essere configurato dall'utente.

Tenendo presente questo, dai un'altra occhiata ai parametri del tag Baz Analytics.

• ID misurazione, id: poiché non viene raccolto automaticamente, è un chiaro esempio di valore che deve essere inserito dall'utente durante la configurazione del tag.
• Nome evento, en: come indicato sopra, il nome dell'evento può essere sempre preso direttamente dal parametro event_name. Tuttavia, poiché il suo valore è definito dall'utente, è una buona idea offrire la possibilità di sostituire il nome, se necessario.
• URL pagina, l: questo valore può essere preso dal page_location parametro, che viene raccolto automaticamente dal tag del browser Google Analytics su ogni evento. Pertanto, non devi richiedere all'utente di inserire un valore manualmente.
• ID utente, u: nel tag del server Baz Analytics, il parametro u non è 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 in più visite al sito web. Come vedrai nell'implementazione 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 memorizzato il cookie. Come l, il u parametro deve essere raccolto automaticamente.

Una volta terminata la configurazione del tag, dovrebbe avere un aspetto simile a questo:

Implementazione dei tag

Ora che la configurazione del tag è stata completata, puoi passare all'implementazione del suo comportamento in JavaScript in sandbox.

Il tag deve fare quattro cose:

1. Recuperare il nome dell'evento dalla configurazione del tag.
2. Recuperare l'URL della pagina dalla proprietà page_location dell'evento.
3. Calcolare un ID utente. Il tag cercherà l'ID utente in un cookie chiamato _bauid. Se il cookie non è presente, il tag calcolerà un nuovo valore e lo memorizzerà per le richieste successive.
4. Costruire un URL ed effettuare una richiesta al server di raccolta di Baz Analytics.

Vale anche la pena di riflettere su come il tag si inserisce nel contenitore nel suo complesso. I diversi componenti del contenitore svolgono ruoli diversi, quindi ci sono anche cose che il tag non fa o non dovrebbe fare. Il tuo tag:

• Non deve esaminare l'evento per capire se deve essere eseguito. Questo è lo scopo di un attivatore.
• Non deve eseguire il contenitore con l'API runContainer. Questo è il compito del client.
• Con l'importante eccezione dei cookie, non deve tentare di interagire direttamente con la richiesta o la risposta. Anche questo è il compito del client.

La scrittura di un modello di tag che esegue una di queste operazioni comporterebbe un comportamento confuso per gli utenti del tag. Ad esempio, un tag che invia una risposta alla richiesta in entrata impedirebbe al client di fare lo stesso. Ciò violerebbe le aspettative degli utenti sul comportamento del contenitore.

Tenendo presente tutto questo, di seguito è riportata un'implementazione annotata del tag in JS in 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 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;
}

A questo punto, il tag è implementato. Prima di poter utilizzare il tag, devi impostare correttamente le relative autorizzazioni API. Vai alla scheda Autorizzazioni dell'editor di 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

Dovresti anche scrivere test per il tag. Per saperne di più sui test dei modelli, consulta la sezione Test della guida per gli sviluppatori di modelli.

Infine, non dimenticare di provare a eseguire il tag almeno una volta con il pulsante Esegui codice. In questo modo, molti errori semplici non verranno inseriti nel server.

Inviare il tag alla Galleria modelli della community

Ora che hai completato il lavoro di creazione, test e deployment di un nuovo tag, non c'è motivo di tenerlo per te. Se ritieni che il tuo nuovo tag possa essere utile ad altre persone, valuta la possibilità di inviarlo alla Galleria modelli della community.

Conclusione

In questo tutorial hai appreso le nozioni di base per la scrittura di un tag per un contenitore del server. Hai imparato a:

• Quali API 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.