Nell'ultima riga dello snippet di misurazione JavaScript viene aggiunto un comando send alla coda dei comandi ga() per inviare una visualizzazione di pagina a Google Analytics:
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');
L'oggetto che esegue l'invio è il tracker la cui creazione è stata pianificata nella riga di codice precedente. I dati che vengono inviati sono i dati memorizzati su quel tracker.
Questa guida descrive i vari modi per inviare dati a Google Analytics e spiega come controllare quali dati vengono inviati.
Hit, tipi di hit e Measurement Protocol
Quando un tracker invia dati a Google Analytics si chiama invio di un hit, e ogni hit deve avere un tipo di hit. Il tag Google Analytics invia un hit di tipo pageview; altri tipi di hit sono screenview, event, transaction, item, social, exception e timing. Questa guida illustra i concetti e i metodi comuni a tutti i tipi di hit. Le guide individuali per ogni tipo di hit sono disponibili nella sezione Misurazione delle interazioni comuni degli utenti nel pannello di navigazione a sinistra.
L'hit è una richiesta HTTP, composta da coppie di campi e valori codificati come stringa di query e inviato a Measurement Protocol.
Se gli strumenti per sviluppatori del tuo browser sono aperti quando carichi una pagina che utilizza analytics.js, puoi visualizzare gli hit inviati nella scheda Rete. Cerca le richieste inviate a google-analytics.com/collect.
Quali dati vengono inviati
Quando inviano un hit a Measurement Protocol, i tracker inviano tutti i campi attualmente archiviati e che sono parametri di Measurement Protocol validi. Ad esempio, i campi come title e location vengono inviati, mentre cookieDomain e hitCallback non lo sono.
In alcuni casi potresti voler inviare campi a Google Analytics per l'hit corrente, ma non per quelli successivi. Un esempio di ciò è un hit da evento in cui i campi eventAction e eventLabel sono pertinenti solo all'hit corrente.
Per inviare campi solo con l'hit corrente, puoi passarli come argomenti al metodo send. Per fare in modo che i dati dei campi vengano inviati con tutti gli hit successivi, devi aggiornare il tracker utilizzando il metodo set.
Il metodo di invio
Il metodo send di un tracker può essere chiamato direttamente sull'oggetto tracker stesso o aggiungendo un comando send alla coda dei comandi ga(). Poiché la maggior parte delle volte non hai un riferimento all'oggetto tracker, si consiglia di usare la coda dei comandi ga() per inviare i dati del tracker a Google Analytics.
Utilizzo della coda di comando ga()
La firma per l'aggiunta di un comando send alla coda dei comandi ga() è la seguente:
ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);
Come già detto, i valori specificati tramite i parametri hitType, ...fields e fieldsObject vengono inviati solo per l'hit corrente. Non vengono memorizzati sull'oggetto tracker e non vengono inviati con gli hit successivi.
Se uno qualsiasi dei campi trasmessi con il comando send è già impostato sull'oggetto tracker, verranno utilizzati i valori trasmessi nel comando al posto dei valori memorizzati sul tracker.
Le chiamate al comando send devono specificare un hitType e, a seconda del tipo specificato, potrebbero essere richiesti anche altri parametri. Per ulteriori dettagli, consulta le singole guide per misurare le interazioni comuni degli utenti nella barra di navigazione a sinistra.
Il modo più semplice per utilizzare il comando send, che funziona per tutti i tipi di hit, è passare tutti i campi con il parametro fieldsObject. Ad esempio:
ga('send', {
hitType: 'event',
eventCategory: 'Video',
eventAction: 'play',
eventLabel: 'cats.mp4'
});
Per praticità, alcuni tipi di hit consentono di passare direttamente i campi di uso comune come argomenti al comando send. Ad esempio, il comando send precedente per il tipo di hit "event" potrebbe essere riscritto come segue:
ga('send', 'event', 'Video', 'play', 'cats.mp4');
Per un elenco completo dei campi che possono essere passati come argomenti per i vari tipi di hit, consulta la sezione "parametri" nel riferimento al metodo di invio.
Utilizzo di un tracker denominato
Se stai utilizzando un tracker denominato anziché il tracker predefinito, puoi trasmetterne il nome nella stringa di comando.
Il seguente comando send verrà chiamato sul tracker denominato "myTracker":
ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');
Sull'oggetto tracker stesso
Se disponi di un riferimento all'oggetto tracker, puoi chiamare direttamente il metodo send di quel tracker:
ga(function(tracker) {
tracker.send('event', 'Video', 'play', 'cats.mp4');
});
Sapere quando l'hit è stato inviato
In alcuni casi è necessario sapere quando un hit viene inviato a Google Analytics per poter intervenire immediatamente dopo. Si tratta di un problema comune quando devi registrare una particolare interazione che allontana l'utente dalla pagina corrente. Molti browser interrompono l'esecuzione di JavaScript non appena la pagina inizia l'unload, il che significa che i comandi analytics.js per inviare hit potrebbero non essere mai eseguiti.
Un esempio è il caso in cui vuoi inviare un evento a Google Analytics per registrare il clic di un utente sul pulsante di invio di un modulo. Nella maggior parte dei casi, se fai clic sul pulsante Invia viene avviata immediatamente il caricamento della pagina successiva e gli eventuali comandi ga('send', ...) non vengono eseguiti.
La soluzione a questo problema è intercettare l'evento per interrompere l'unload della pagina. Successivamente, puoi inviare l'hit a Google Analytics come al solito e una volta completato l'invio, puoi inviare nuovamente il modulo in modo programmatico.
hitCallback
Per ricevere una notifica quando termina l'invio di un hit, imposta il campo hitCallback. hitCallback è una funzione che viene chiamata non appena l'hit viene inviato correttamente.
L'esempio seguente mostra come annullare l'azione di invio predefinita di un modulo, inviare un hit a Google Analytics e inviare nuovamente il modulo utilizzando la funzione hitCallback:
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: function() {
form.submit();
}
});
});
Gestione dei timeout
L'esempio riportato sopra funziona bene, ma presenta un problema serio. Se per qualsiasi motivo la libreria analytics.js non viene caricata, la funzione hitCallback non verrà mai eseguita. Se la funzione hitCallback non viene mai eseguita, gli utenti non potranno mai inviare il modulo.
Ogni volta che inserisci una funzionalità fondamentale del sito nella funzione hitCallback, devi sempre usare una funzione di timeout per gestire i casi in cui la libreria analytics.js non viene caricata.
L'esempio successivo aggiorna il codice riportato sopra in modo da utilizzare un timeout. Se è trascorso un secondo dopo che l'utente ha fatto clic sul pulsante di invio e l'hitCallback non è stato eseguito, il modulo viene comunque inviato nuovamente.
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Creates a timeout to call `submitForm` after one second.
setTimeout(submitForm, 1000);
// Keeps track of whether or not the form has been submitted.
// This prevents the form from being submitted twice in cases
// where `hitCallback` fires normally.
var formSubmitted = false;
function submitForm() {
if (!formSubmitted) {
formSubmitted = true;
form.submit();
}
}
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: submitForm
});
});
Se utilizzi il pattern precedente in molti punti del sito, probabilmente è più semplice creare una funzione di utilità per gestire i timeout.
La seguente funzione di utilità accetta una funzione come input e restituisce una nuova funzione. Se la funzione restituita viene chiamata prima del periodo di timeout (il timeout predefinito è un secondo), cancella il timeout e richiama la funzione di input. Se la funzione restituita non viene chiamata prima del periodo di timeout, viene comunque richiamata la funzione di input.
function createFunctionWithTimeout(callback, opt_timeout) {
var called = false;
function fn() {
if (!called) {
called = true;
callback();
}
}
setTimeout(fn, opt_timeout || 1000);
return fn;
}
Ora puoi includere facilmente tutte le funzioni di hitCallback con un timeout per assicurarti che il tuo sito funzioni come previsto anche nei casi in cui gli hit non vengono inviati o la libreria analytics.js non viene mai caricata.
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: createFunctionWithTimeout(function() {
form.submit();
})
});
});
Specificare diversi meccanismi di trasporto
Per impostazione predefinita, analytics.js seleziona il metodo HTTP e il meccanismo di trasporto con cui inviare hit in modo ottimale. Le tre opzioni sono 'image' (con un oggetto Image), 'xhr' (con un oggetto XMLHttpRequest) o 'beacon' con il nuovo metodo navigator.sendBeacon.
I due metodi precedenti condividono il problema descritto nella sezione precedente (in cui spesso gli hit non vengono inviati se la pagina è in fase di unload). Il metodo navigator.sendBeacon, al contrario, è una nuova funzionalità HTML creata per risolvere questo problema.
Se il browser degli utenti supporta navigator.sendBeacon, puoi specificare 'beacon' come meccanismo transport e non devi preoccuparti di impostare un callback di hit.
Il codice seguente imposta il meccanismo di trasporto su 'beacon' nei browser che lo supportano.
ga('create', 'UA-XXXXX-Y', 'auto');
// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');
Passaggi successivi
A volte, la misurazione di determinati tipi di interazioni degli utenti può richiedere implementazioni complesse. Tuttavia, in molti casi queste implementazioni sono già state sviluppate e rese disponibili come plug-in analytics.js. La guida successiva spiega come utilizzare i plug-in analytics.js con la coda dei comandi ga().