Tracciare in Google Analytics gli accessi e le azioni degli Utenti in uno Spreadsheet

Google Analytics, oltre a tracciare le visualizzazioni delle pagine di un sito web da parte degli utenti e le relative azioni effettuate su di esse, può essere utilizzato anche per monitorare le visite ad uno Spreadsheet e le azioni di modifica avvenute sui suoi fogli, per mezzo del protocollo di misurazione, tramite poche righe di codice in Apps Script da inserire nell'editor di script associato (bound-script) allo Spreadsheet che si intende tracciare.

Gli script è associati, a un Foglio di Google così come ad un Documento Google o a un Google Form, si comportano generalmente come script autonomi, tranne per il fatto che non vengono visualizzati in Google Drive, non possono essere scollegati dal file a cui sono associati e, a differenza degli script autonomi (standalone), possono chiamare alcuni metodi riferiti al file principale (ad esempio, getActiveSpreadsheet() per riferirsi allo Spreadsheet in uso, getActiveSheet() per riferirsi al relativo foglio attualmente in uso, ecc...). Per maggiori informazioni rimando alla documentazione ufficiale, bound script.

Un'altra caratteristica degli script associati è quella di poter utilizzare i cosiddetti trigger semplici (Simple Triggers), come ad esempio la funzione speciale onOpen() che viene eseguita automaticamente ogni volta che un file viene aperto da un utente con accesso di modifica, onEdit() che viene eseguita automaticamente ogni volta che un file viene modificato (ad esempio la modifica di un valore in una cella di uno Spreadsheet) oppure onInstall() eseguita quando viene installata un'add-on.

Come tutti i tipi di script, possono anche utilizzare trigger installabili e questa è la caratteristica che fa al caso nostro in quanto, poiché i trigger semplici avvengono automaticamente in modo silenzioso e anonimo, sono soggetti a numerose restrizioni (come indicato nella relativa referenza ufficiale il cui link per accedervi è riportato poco sopra), di conseguenza non sono in grado di eseguire nessuna funzione che richiede un'autorizzazione dell'utente. Con gli script installabili invece possiamo definire quando eseguire una determinata funzione in base ad una azione avvenuta nel documento dove è presente lo script associato.

Nell'esempio di questo tutorial ho creato due funzioni, GA_Pageview() e GA_Event(), rispettivamente per l'invio di una pageview all'apertura dello Spreadsheet e per l'invio di un evento alla modifica di righe, colonne o celle nei relativi fogli.

A queste due funzioni ho assegnato un trigger installabile dal menu 'Modifica -> Trigger del progetto corrente' impostandoli come nell'immagine seguente, Fig. 1:

Fig. 1 - Trigger installabili, per pageview ed eventi, avviati su azioni derivanti dal foglio di lavoro relative all'apertura o in caso di modifica

Il codice completo da inserire come script associato (bound-script) all'interno di uno Spreadsheet, dal menu 'Strumenti -> Editor di script...', è il seguente:

function rndCID() {
  var userProperties = PropertiesService.getUserProperties();
  var cid = userProperties.getProperty('cid');
  if (cid != null) {
    return cid;
  }
  cid = Utilities.getUuid();
  userProperties.setProperty('cid', cid);
  return cid;
}

function GA_Pageview(e) {
  /*
  var authMode = e.authMode;
  var source = e.source;
  var triggerUid = e.triggerUid;
  // Es: {authMode=FULL, source=Spreadsheet, triggerUid=2060928213}
  */
  sendGoogleAnalyticsHit('pageview', '', '', '');
}

function GA_Event(e) {
  /*
  var authMode = e.authMode;
  var changeType = e.changeType;  
  var source = e.source;
  var triggerUid = e.triggerUid;
  // {authMode=FULL, changeType=EDIT, source=Spreadsheet, triggerUid=1672549640}
  */

  sendGoogleAnalyticsHit('event', e.source, e.changeType, SpreadsheetApp.getActiveSpreadsheet().getSheetName());
}

function sendGoogleAnalyticsHit(hitType, evtCategory, evtAction, evtLabel) {

  var gaProperty = 'UA-1234567-12'; // <-- Proprietà di Google Analytics verso la quale si vogliono inviare le informazioni di tracciamento
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var ss_url = ss.getUrl();
  var ss_url_noprotocol = ss_url.split("//")[1];
  var dh = ss_url_noprotocol.split(/\/(.+)/)[0];
  var dp = ss_url_noprotocol.split(/\/(.+)/)[1];
  var dt = ss.getName();
    
  // Valore anonimizzato per il ClientID, obbligatorio per GA 
  var cid = rndCID();
  
  // Valore random (es: 1517792632) per evitare il problema del 'browser caching'
  var z = Math.round(Date.now() / 1000).toString();
  
  var data = {
    'v' : '1',
    't': hitType,
    'tid': gaProperty,
    'cid': cid,
    'dh' : dh,
    'dp' : "/" + dp,
    'dt' : dt,
    'dl' : ss_url,
    "z" : z    
  };
  
  if (hitType == 'event') {
    data["ec"] = evtCategory;
    data["ea"] = evtAction;
    data["el"] = evtLabel;
  }
  
  var payload = Object.keys(data).map(function(key) {
    return encodeURIComponent(key) + '=' + encodeURIComponent(data[key]);
  }).join('&');
  
  var options = {
    'method' : 'POST',
    'payload' : payload
  };

  UrlFetchApp.fetch('http://www.google-analytics.com/collect', options);
}

Sia GA_Pageview() che GA_Event() richiamano la funzione sendGoogleAnalyticsHit() passandogli i rispettivi parametri.
Per quanto riguarda la pageview viene inviata solo l'informazione del tipo di hit, appunto pageview, mentre per l'evento oltre al tipo di hit, event, vengono passate le informazioni di categoria, azione ed etichetta dell'evento che, nel caso specifico, sono e.source (il tipo di documento: Spreadsheet, Document o Form), e.changeType (l'azione effettuata, ad esempio: EDIT, INSERT_ROW, INSERT_COLUMN, ecc...) e SpreadsheetApp.getActiveSpreadsheet().getSheetName() (il nome del foglio nel quale viene scaturito l'evento, esempio: Foglio1).
Per maggiori informazioni sull'oggetto Event per Sheets, Docs e Forms rimando la consultazione alla documentazione ufficiale.

Per garantire la completezza del dato su Google Analytics, sia per le pageview che per gli eventi, vengono inviate le informazioni di pagina (hostname, URI, URL e titolo del documento), il parametro z (ovvero un valore random per evitare il problema del browser caching per invii di hit ripetuti contenenti informazioni precedentemente inviate), il clientId (detto cid, un valore anonimizzato per il dispositivo in uso dall'utente, obbligatorio per Analytics in assenza dello userId) e l'id della Proprietà di Analytics (esempio, UA-1234567-12) verso la quale si intendono inviare le informazioni di tracciamento (questo è l'unico valore che, per ovvi motivi, necessita di essere personalizzato prima dell'uso dello script).

Dopo aver lanciato lo script la prima volta e completato il flusso per l'autorizzazione dei Google Services nei progetti in Apps Script, sarà possibile iniziare a giocare con il nostro Foglio di Google, aprendolo, modificando qualche cella ed inserendo o rimuovendo righe e colonne.

Sarà possibile verificare subito su Analytics, in tempo reale, l'avvenuta acquisizione delle informazioni e dopo alcuni minuti ritrovarle consolidate nei report standard di pagine, Fig. 2 ed eventi, Fig. 3:

Fig. 2 - Report di Pagine su Google Analytics dove è mostrato l'URI della pagina ed il suo titolo

Fig. 3 - Report di Eventi su Google Analytics dove è mostrata la Categoria e l'Azione dell'evento

Scegliendo l'opportuna dimensione secondaria nei report di cui sopra è possibile visualizzare anche le altre informazioni inviate ad Analytics quali ad esempio il nome host (docs.google.com) oppure l'etichetta dell'evento (Foglio1, Foglio2, ...).

Un metodo alternativo per il tracciamento dell'apertura di uno Spreadsheet lo trovate nel tutorial 'Tracciare in Analytics l'apertura di uno Spreadsheet con una Funzione Custom'.