JavaScript, HTML, CSS e... !
2 commenti

Tracciamento di pageview ed event

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:



trigger installabili per pageview ed eventi

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:



report di pagine su google analytics con l'uri della pagina ed il suo titolo

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




report di eventi su google analytics con la categoria e l'azione dell'evento

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'.

Tags

Michele Pisani

Michele Pisani

Sviluppatore Javascript ed esperto in Digital Analytics

L'esperienza nel settore Digital Analytics unita ad anni di sviluppo in Javascript ha trovato la massima espressione in Google Apps Script che mi ha permesso, con estrema facilità e poche righe di codice, di realizzare potenti applicazioni interattive e processi automatizzati integrati con i prodotti della G Suite.

Come contattarmi
scrivi un commento

2 Commenti

  1. Monday, April 15, 2019 alle ore 16:05 domenico

    Ciao Michele , scusa se insisto (ma ti rifaccio una domanda che ti avevo già fatto, ma volevo essere sicuro di essermi spiegato bene) ho creato un file spreadsheet condiviso con altre persone. Tramite codice script legato al file google recuperare un elenco (al momento dell'apertura del file -onOpen() che mi fornisse quali utenti ci sono gia in visualizzazione , in modo che se ce ne fossero altri gia in visualizzazione non permetto la prosecuzione. Cosi facendo otterrei che la visualizzazione dei file google sia aperto sempre e cmq da un solo account.
    Google lo fa benissimo mi fa vedere chi è aperto oltre me e addirittura anche su quale cella. Esiste qualche funzione che mi possa permettere di ottenere ciò?

    Rispondi a questo commento
    • Monday, April 15, 2019 alle ore 22:57 Michele PisnaiAutore

      Ciao Domenico,
      come ti avevo accennato tramite un altro canale, che io sappia la funzionalità di cui hai bisogno non è (o non è ancora) supportata.
      Come workaround che mi può venire in mente c'è quello di provare a memorizzare costantemente l'attività sullo Sheet con un trigger che cattura le modifiche, in questo modo (con i dovuti accorgimenti) dovresti poter controllare se un utente fa una modifica dopo un altro ed in quale lasso di tempo.

      Rispondi a questo commento

Scrivi un commento

Il tuo indirizzo email non sarà pubblicato.I campi contrassegnati da un * sono obbligatori
Puoi utilizzare i seguenti tag nei commenti:
[bold]testo[/bold] se vuoi evidenziare un testo con il grassetto[code]function helloworld() { }[/code] se vuoi pubblicare una porzione di codice[url]https://www.appsscript.it[/url] se devi riferirti ad un indirizzo web