Inviare dati a Google Analytics

L'ultima riga dello snippet misurazione JavaScript aggiunge un comando send alla coda di 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 che è stato programmato per la creazione nella riga di codice precedente. I dati che vengono inviati sono quelli memorizzati su quel tracker.

Questa guida descrive i vari modi per inviare dati a Google Analytics e spiega come controllare i dati che vengono inviati.

Hit, tipi di hit e Measurement Protocol

Quando un tracker invia dati a Google Analytics si parla di 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 singole guide per ciascun tipo di hit sono disponibili nella sezione Misurazione delle interazioni comuni degli utenti nel menu di navigazione a sinistra.

L'hit è una richiesta HTTP composta da coppie di campo e valore codificate come stringa di query e inviato a Measurement Protocol.

Se gli strumenti per sviluppatori del 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 sono parametri di Measurement Protocol validi. Ad esempio, vengono inviati campi come title e location, al contrario di cookieDomain e hitCallback.

In alcuni casi, potresti dover 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, consigliamo di utilizzare la coda di comando ga() per inviare i dati del tracker a Google Analytics.

Utilizzo della coda di comandi ga()

La firma per l'aggiunta di un comando send alla coda dei comandi di ga() è la seguente:

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

Come indicato in precedenza, 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 hit successivi.

Se uno dei campi passati con il comando send è già impostato sull'oggetto tracker, verranno utilizzati i valori trasferiti nel comando anziché i 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 nel riquadro di navigazione a sinistra.

Il modo più semplice per utilizzare il comando send, valido per tutti i tipi di hit, è trasmettere tutti i campi utilizzando 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 campi di uso comune come argomento al comando send. Ad esempio, il comando send precedente per il tipo di hit "evento" potrebbe essere riscritto come:

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" del riferimento al metodo di invio.

Utilizzo di un tracker denominato

Se utilizzi un tracker denominato anziché il tracker predefinito, puoi passare il relativo nome nella stringa di comando.

Il seguente comando send verrà richiamato 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 in seguito. Si tratta di un problema comune quando è necessario registrare una particolare interazione che porterebbe un utente lontano dalla pagina corrente. Molti browser interrompono l'esecuzione di JavaScript non appena inizia l'unload della pagina, il che significa che i comandi analytics.js per inviare hit potrebbero non essere mai eseguiti.

Un esempio di ciò si verifica quando 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, la pagina successiva viene caricata immediatamente e qualsiasi comando ga('send', ...) non viene eseguito.

La soluzione è intercettare l'evento per interrompere l'unload della pagina. Puoi quindi inviare l'hit a Google Analytics come di consueto e, una volta completato l'invio, puoi inviare nuovamente il modulo in modo programmatico.

hitCallback

Per ricevere una notifica al termine dell'invio di un hit, imposta il campo hitCallback. hitCallback è una funzione che viene richiamata 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 poi 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 grave. Se (per qualsiasi motivo) la libreria analytics.js non viene caricata, la funzione hitCallback non verrà mai eseguita. Inoltre, se la funzione hitCallback non viene mai eseguita, gli utenti non potranno mai inviare il modulo.

Ogni volta che inserisci funzionalità critiche del sito nella funzione hitCallback, dovresti sempre utilizzare 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 Invia e l'hitCallback non è stato eseguito, il modulo viene comunque inviato di nuovo.

// 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 stai utilizzando il pattern sopra riportato in molti punti del sito, probabilmente è più facile 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 è di un secondo), il timeout viene cancellato e viene richiamata la funzione di input. Se la funzione restituita non viene chiamata prima del periodo di timeout, viene richiamata comunque 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 hitCallback con un timeout per assicurarti che il tuo sito funzioni come previsto anche nei casi in cui gli hit non vengano inviati o la libreria analytics.js non venga 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 in modo ottimale gli hit. 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 viene scaricata). Il metodo navigator.sendBeacon, invece, è una nuova funzionalità HTML creata per risolvere questo problema.

Se il browser dell'utente 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

La misurazione di determinati tipi di interazioni degli utenti a volte 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 di comandi ga().