Attività

Questa guida descrive le attività, una funzionalità avanzata utilizzata per personalizzare il modo in cui analytics.js convalida, crea e invia le richieste di Measurement Protocol.

Panoramica

Ogni volta che viene chiamato il comando send, analytics.js esegue una sequenza di attività per convalidare, creare e inviare una richiesta Measurement Protocol dal browser dell'utente a Google Analytics. La tabella seguente descrive ciascuna di queste attività nell'ordine in cui vengono eseguite:

Nome attività Descrizione
customTask Per impostazione predefinita, questa attività non esegue alcuna azione. Sostituiscilo per fornire un comportamento personalizzato.
previewTask Interrompi la richiesta se la pagina viene visualizzata solo per generare una miniatura "Siti principali" per Safari.
checkProtocolTask Interrompi la richiesta se il protocollo della pagina non è http o https.
validationTask Interrompi la richiesta se i campi obbligatori sono mancanti o non sono validi.
checkStorageTask Interrompe la richiesta se il tracker è configurato per utilizzare i cookie, ma nel browser dell'utente i cookie sono disabilitati.
historyImportTask Importa le informazioni dai cookie ga.js e urchin.js per preservare la cronologia dei visitatori quando viene eseguita la migrazione di un sito a Universal Analytics.
samplerTask Campiona i visitatori in base all'impostazione sampleRate per questo tracker.
buildHitTask Crea una stringa di richiesta di Measurement Protocol e la memorizza nel campo hitPayload.
sendHitTask Trasmette la richiesta di Measurement Protocol archiviata nel campo hitPayload ai server di Google Analytics.
timingTask Genera automaticamente un hit di tempo relativo alla velocità del sito in base all'impostazione siteSpeedSampleRate di questo tracker.
displayFeaturesTask Invia un hit aggiuntivo se le funzionalità di visualizzazione sono attivate e non è stato inviato un hit precedente entro il periodo di timeout impostato dal cookie delle funzionalità pubblicitarie (_gat).

Ognuna di queste attività viene implementata come una funzione JavaScript che prende come input un singolo parametro del modello. Il modello è un oggetto semplice che consente di accedere a uno qualsiasi dei campi definiti nella Guida di riferimento ai campi di Analytics.js.

È possibile accedere alle attività o sostituirle con i metodi di monitoraggio standard get e set. Con questi metodi, puoi sostituire le attività con funzioni personalizzate o aumentare la funzionalità esistente concatenandole in modo che vengano eseguite prima o dopo un'attività esistente.

Implementazione

Questa sezione descrive come aggiungere nuove funzionalità alle attività esistenti, sostituire le funzioni integrate nelle attività con un codice personalizzato o disattivare completamente una funzione dell'attività.

Eseguire l'override di un'attività

Per eseguire l'override di un'attività, puoi set il suo valore in una funzione che fa qualcosa di diverso. Un motivo comune per eseguire l'override delle attività è lo stub della funzionalità durante il test delle implementazioni di analytics.js.

Il seguente codice sostituisce sendHitTask con una funzione che registra il payload degli hit nella console:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

Aggiunta a un'attività in corso...

Per inserire una nuova funzionalità, puoi concatenare la funzione di attività personalizzata in modo che venga eseguita prima o dopo un'attività esistente. Nell'esempio seguente, sendHitTask viene sostituito con una funzione di attività personalizzata che prima chiama la funzione sendHitTask originale per inviare il beacon di richiesta normale a google-analytics.com/collection, poi esegue un codice personalizzato per inviare una copia della richiesta di Measurement Protocol a un server locale.

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

Interruzione dell'elaborazione dell'attività

Un'attività può interrompere l'elaborazione delle attività successive generando un'eccezione. Se l'attività che genera l'eccezione viene eseguita prima del giorno sendHitTask, la richiesta di Measurement Protocol non viene inviata ai server di Google Analytics. Nell'esempio seguente, interrompiamo la richiesta ogni volta che il browser dell'utente contiene un cookie denominato "testing" con il valore "true".

ga('create', 'UA-XXXXX-Y', 'auto');

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

Disattivazione di un'attività

Per disabilitare una qualsiasi delle funzioni dell'attività integrate, sostituiscila con un valore null.

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');