Scrittura dei plug-in

I plug-in sono script che migliorano la funzionalità di analytics.js e aiutano a risolvere i problemi e a misurare le interazioni degli utenti. Questa guida descrive il processo di scrittura dei tuoi plug-in analytics.js. Per informazioni su come utilizzare i plug-in analytics.js nelle implementazioni personali, consulta Utilizzo dei plug-in.

Definizione di un plug-in

I plug-in vengono definiti tramite il comando provide, che deve essere richiamato con il nome del plug-in come primo argomento seguito dalla funzione costruttore del plug-in. Quando viene eseguito il comando provide, registra il plug-in da utilizzare con la coda di comandi ga().

Il plug-in dei plug-in

Di seguito è riportato l'esempio più semplice di un plug-in analytics.js:

// Defines the plugin constructor.
function MyPlugin() {
  console.log('myplugin has been required...');
}

// Registers the plugin for use.
ga('provide', 'myplugin', MyPlugin);

I plug-in devono funzionare correttamente anche nei casi in cui l'oggetto ga globale è stato rinominato, pertanto se stai scrivendo un plug-in per un utilizzo di terze parti, devi includere un controllo per verificare se la variabile GoogleAnalyticsObject è stata impostata su una stringa diversa da 'ga'. La seguente funzione providePlugin esegue questa operazione:

// Provides a plugin name and constructor function to analytics.js. This
// function works even if the site has customized the ga global identifier.
function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

Configurazione delle istanze plug-in

Quando la coda dei comandi ga() esegue un comando require, crea un'istanza di un nuovo oggetto utilizzando l'operatore new sulla funzione costruttore del plug-in provide. Il costruttore viene passato all'oggetto tracker come primo argomento e le eventuali opzioni di configurazione vengono trasmesse al comando require come secondo argomento.

Prendi in considerazione il seguente comando require aggiunto al tag Google Analytics:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'localHitSender', {path: '/log', debug: true});
ga('send', 'pageview');

E il codice di localHitSender:

function LocalHitSender(tracker, config) {
  this.path = config.path;
  this.debug = config.debug;
  if (this.debug) {
    console.log('localHitSender enabled for path: ' + this.path);
    console.log('on tracker: ' + tracker.get('name'));
  }
}

providePlugin('localHitSender', LocalHitSender);

Quando viene eseguito il comando require, nella console viene registrato quanto segue (tieni presente che il nome del tracker predefinito è "t0"):

// localHitSender enabled for path: /log
// on tracker: t0

Definizione dei metodi dei plug-in

I plug-in possono esporre i propri metodi che possono essere richiamati utilizzando la sintassi della coda di comando ga:

ga('[trackerName.]pluginName:methodName', ...args);

dove trackerName è facoltativo e methodName corrisponde al nome di una funzione sul prototipo del costruttore plug-in. Se methodName non esiste nel plug-in o se il plug-in non esiste, si verificherà un errore.

Esempi di chiamate al metodo di plug-in:

// Execute the 'doStuff' method using the 'myplugin' plugin.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'myplugin');
ga('myplugin:doStuff');

// Execute the 'setEnabled' method of the 'hitCopy' plugin on tracker 't3'.
ga('create', 'UA-XXXXX-Y', 'auto', {name: 't3'});
ga('t3.require', 'hitcopy');
ga('t3.hitcopy:setEnabled', false);

Esempi di definizioni dei metodi per i plug-in:

// myplugin constructor.
var MyPlugin = function(tracker) {
};

// myplugin:doStuff method definition.
MyPlugin.prototype.doStuff = function() {
  alert('doStuff method called!');
};

// hitcopy plugin.
var HitCopy = function(tracker) {
};

// hitcopy:setEnabled method definition.
HitCopy.prototype.setEnabled = function(isEnabled) {
  this.isEnabled = isEnabled;
}:

Caricamento dei plug-in

In genere i plug-in vengono caricati da un file JavaScript separato o abbinati al codice dell'applicazione principale.

<script async src="myplugin.js"></script>

I plug-in non devono necessariamente essere definiti prima di essere richiesti. Poiché analytics.js viene caricato in modo asincrono e spesso anche i plug-in vengono caricati in modo asincrono, la coda dei comandi ga() è stata creata per gestire questa situazione.

Se la coda di comando riceve un comando require per un plug-in che non è stato ancora fornito, interromperà l'esecuzione degli elementi rimanenti nella coda fino a quando il plug-in non sarà disponibile.

Il codice seguente mostra in che modo il comando ga('require', 'myplugin') non viene effettivamente eseguito finché non viene rilevato il comando ga('provide', 'myplugin', ...), tre secondi dopo.

ga('require', 'myplugin');

function MyPlugin() {
  console.log('myplugin has been required...');
}

// Waits 3 second after running the `require`
// command before running the `provide` command.
setTimeout(function() {
  ga('provide', 'myplugin', MyPlugin);
}, 3000);

Esempi

Il seguente plug-in di esempio è progettato per acquisire i valori della campagna personalizzata dall'URL di una pagina e trasmetterli al tracker. Questo plug-in mostra come definire e registrare uno script per il plug-in, passare i parametri di configurazione del plug-in e definire e chiamare i metodi del plug-in.

// campaign-loader.js

function providePlugin(pluginName, pluginConstructor) {
  var ga = window[window['GoogleAnalyticsObject'] || 'ga'];
  if (typeof ga == 'function') {
    ga('provide', pluginName, pluginConstructor);
  }
}

/**
 * Constructor for the campaignLoader plugin.
 */
var CampaignLoader = function(tracker, config) {
  this.tracker = tracker;
  this.nameParam = config.nameParam || 'name';
  this.sourceParam = config.sourceParam || 'source';
  this.mediumParam = config.mediumParam || 'medium';
  this.isDebug = config.debug;
};

/**
 * Loads campaign fields from the URL and updates the tracker.
 */
CampaignLoader.prototype.loadCampaignFields = function() {
  this.debugMessage('Loading custom campaign parameters');

  var nameValue = getUrlParam(this.nameParam);
  if (nameValue) {
    this.tracker.set('campaignName', nameValue);
    this.debugMessage('Loaded campaign name: ' + nameValue);
  }

  var sourceValue = getUrlParam(this.sourceParam);
  if (sourceValue) {
    this.tracker.set('campaignSource', sourceValue);
    this.debugMessage('Loaded campaign source: ' + sourceValue);
  }

  var mediumValue = getUrlParam(this.mediumParam);
  if (mediumValue) {
    this.tracker.set('campaignMedium', mediumValue);
    this.debugMessage('Loaded campaign medium: ' + mediumValue);
  }
};

/**
 * Enables / disables debug output.
 */
CampaignLoader.prototype.setDebug = function(enabled) {
  this.isDebug = enabled;
};

/**
 * Displays a debug message in the console, if debugging is enabled.
 */
CampaignLoader.prototype.debugMessage = function(message) {
  if (!this.isDebug) return;
  if (console) console.debug(message);
};

/**
 * Utility function to extract a URL parameter value.
 */
function getUrlParam(param) {
  var match = document.location.search.match('(?:\\?|&)' + param + '=([^&#]*)');
  return (match && match.length == 2) ? decodeURIComponent(match[1]) : '';
}

// Register the plugin.
providePlugin('campaignLoader', CampaignLoader);

Il codice riportato sopra può essere incluso in una pagina HTML come segue:

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

ga('create', 'UA-XXXXX-Y', 'auto');
ga('require', 'campaignLoader', {
  debug: true,
  nameParam: 'cname',
  sourceParam: 'csrc',
  mediumParam: 'cmed'
});
ga('campaignLoader:loadCampaignFields');

ga('send', 'pageview');
</script>

<!--Note: plugin scripts must be included after the tracking snippet. -->
<script async src="campaign-loader.js"></script>

Plug-in AutoTrack

La libreria autotrack è open source, disponibile su GitHub e include diversi plug-in analytics.js utili per il monitoraggio delle interazioni comuni degli utenti. Per capire meglio come funzionano i plug-in, consulta il codice sorgente della traccia automatica.