Tracciare in Analytics l'apertura di uno Spreadsheet con una Funzione Custom

Nel tutorial 'Tracciare in Google Analytics gli accessi e le azioni degli Utenti in uno Spreadsheet' ho mostrato un esempio di codice che invia pageview ed eventi ad Analytics in base all'attivazione di trigger installabili basati su interazioni con il documento principale (quello al quale è associato lo script, bound-script).

Di seguito propongo un metodo alternativo per il tracciamento dell'apertura di uno Spreadsheet con Google Analytics che sfrutta, anche in questo caso, il protocollo di misurazione di Analytics ma che a livello di Apps Script non si avvale di nessun trigger e non richiede nessun tipo di autorizzazione da parte dell'utente. Quello che sarà presente in Apps Script è una funzione personalizzata (chiamata nel caso specifico GOOGLEANALYTICS) da utilizzare direttamente nell'interfaccia dello Spreadsheet all'interno di una cella come una qualsiasi altra funzione integrata (per intendersi =SOMMA, =CONCATENA, ecc...).
Per maggiori informazioni sulle funzioni personalizzate può essere utile leggere l'articolo 'Funzioni personalizzate in Google Sheets con Google Apps Script', mentre per approfondimenti e dettagli rimando alla documentazione ufficiale Custom Functions in Google Sheets.

Il tracciamento in questione è effettuato tramite l'invio di un hit di tipo evento ad Analytics che richiede di specificare almeno una categoria ed un'azione, il principio si basa sul fatto che la funzione viene eseguita all'apertura dello Spreadsheet per restituirne il risultato in formato di URL. Sapendo che il risultato di una chiamata a google-analytics.com/collect (quella effettuata da Google per inviare le informazioni di tracciamento ad Analytics) è un'immagine di 1x1 px, affinché la funzione personalizzata GOOGLEANALYTICS vada a buon fine si dovrà incapsularla in una funzione dello Spreadsheet che richiama un'immagine dal web e che, nella fattispecie, è chiamata =IMAGE.

La funzione GOOGLEANALYTICS accetta 4 parametri da specificare manualmente: l'id della Proprietà di Analytics verso la quale si intende inviare le hits (es: UA-1234567-12) e le informazioni di categoria (es, il tipo di file: Spreadsheet), azione (l'azione effettuata, es: opened) ed etichetta (es, il nome del file: Tracciare in Google Analytics l'apertura di uno Spreadsheet) dell'evento; al resto dei parametri (alcuni obbligatori per il successo dell'operazione, come ad esempio il cid, spiegato più in dettaglio nell'altro tutorial menzionato ad inizio articolo) penserà lo script.

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

=IMAGE(GOOGLEANALYTICS("UA-1234567-12"; "Spreadsheet"; "opened"; "Tracciare in Google Analytics l'apertura di uno Spreadsheet"))

La parte di codice commentata al di sopra della funzione ha lo scopo di far riconoscere tale formula al sistema di autocompletamento dello Spreadsheet nonché mostrare all'utente indicazioni informative sul tipo di formula e sui relativi parametri, Fig. 1:

Fig. 1 - Funzione personalizzata GOOGLEANALYTICS incorporata nella funzione IMAGE

Dopo il salvataggio del codice nell'editor di script , all'interno di una qualsiasi cella di uno dei fogli dello Spreadsheet (suggerirei di creare un foglio dedicato per questo tipo di impostazioni in modo che non ci sia il rischio di alterazione del contenuto della cella o eventualmente prevedere un colore di sfondo per riconoscere a colpo d'occhio che tale cella contiene una formula) inserire la formula personalizzata con la seguente sintassi:

/**
 * Tracciare l'apertura di uno Spreadsheet in Google Analytics
 *
 * @param {string} gaProperty L'id della Proprietà di Google Analytics, es: UA-1234567-12.
 * @param {string} gaCategory La Categoria dell'evento, es: il tipo di file (Spreadsheet).
 * @param {string} gaAction L'Azione dell'evento, es: l'azione effettuata (opened).
 * @param {string} gaLAbel L'Etichetta dell'evento, es: il nome del file (Tutorial per il tracciamento in Analytics).
 * @return Un'immagine in formato GIF di 1x1 (px) che è il risultato della chiamata di tracciamento
 * @customfunction
 */

function GOOGLEANALYTICS(gaProperty, gaCategory, gaAction, gaLabel) {

  // Valore anonimizzato per il ClientID, obbligatorio per GA 
  var cid = Utilities.getUuid();
  
  // Valore random (es: 1517792632) per evitare il problema del 'browser caching'
  var z = Math.round(Date.now() / 1000).toString();
  
  var imageURL = [
    "https://ssl.google-analytics.com/collect",
    "?v="   + "1",
    "&t="   + "event",
    "&tid=" + gaProperty,
    "&cid=" + cid,
    "&ec="  + encodeURIComponent(gaCategory || "not specified"),
    "&ea="  + encodeURIComponent(gaAction || "not specified"),
    "&el="  + encodeURIComponent(gaLabel || "not specified"),
    "&z="   + z  
  ].join("");
  
  return imageURL;
  
}

Dopo aver salvato il Foglio di calcolo sarà possibile provare ad effettuare il refresh dello stesso e/o ad aprirlo da altri account (previa condivisione) in modo da poter constatare da Analytics l'effettiva acquisizione dei tracciamenti con le informazioni passate alla funzione, Fig. 2:

Fig. 2 - Report 'In tempo reale' di Google Analytics che mostra l'acquisizione dei tracciamenti