Generare report non campionati in Google Analytics con Google Apps Script

Google Analytics 360 fornisce l'accesso ad alcuni strumenti avanzati dei propri servizi tra i quali, i Rapporti non campionati (Unsampled Reports).

Lavorando dall'interfaccia di Google Analytics (o da altri strumenti di recupero dei dati da tale piattaforma) per la generazione di un report, può capitare, soprattutto selezionando un periodo di tempo ampio, che la richiesta si basi su un cospicuo numero di sessioni, con la conseguenza che in interfaccia venga mostrata una notifica nella parte superiore del report: Questo rapporto si basa su N sessioni. Questo messaggio informa che il report si basa su dati campionati. Il campionamento avviene automaticamente quando, per la generazione del report, vengono raccolte più di 500.000 sessioni a livello di Proprietà in Google Analytics (il numero sale a 100 milioni a livello di vista per Google Analytics 360).

A seconda dell'accuratezza del dato che si intende ottenere, tale comportamento può generare anomalie ed incongruenze e non permette di effettuare analisi puntuali sulle informazioni raccolte.

Con Google Analytics 360, tuttavia, gli utenti che dispongono dell'autorizzazione alla collaborazione nell'account possono creare rapporti non campionati (ovvero il cui dato si basa su tutte le sessioni senza alcun tipo di soglia).
Il servizio ovviamente non è gratuito, inoltre, richiedendo un notevole carico di elaborazione, l'accesso a questa funzione è limitato da una quota giornaliera applicata a livello di Proprietà e condivisa a livello di vista.

La generazione di tali report può avvenire da interfaccia dove, selezionato il report di interesse (la funzionalità non è prevista per tutti i report), basterà cliccare su Esporta, nella barra dei menu in alt a destra, e selezionare Rapporto non campionato assegnandovi un nome.

I report non campionati non sono generati immediatamente, per visualizzare tutti i rapporti non campionati richiesti è necessario entrare in Personalizzazione -> Rapporti non campionati dove sarà possibile verificare lo stato di disponibilità di ognuno di essi (In attesa o Completato). Quando lo stato del rapporto è Completato, è possibile cliccare su CSV per scaricarlo.

Con Google Apps Script e le Unsampled Reports API di Google Analytics è possibile gestire il flusso di generazione ed elaborazione dei report non campionati in maniera automatizzata.

Il codice proposto di seguito prevede due distinte funzioni, insertUnsampledReport() per la generazione del report non campionato e getUnsampledReport() per il recupero dei dati dal report precedentemente generato.
Di seguito il codice (successivamente dettagliato):

// Unsampled Report API
// AppsScript.it
// https://developers.google.com/analytics/devguides/config/mgmt/v3/mgmtReference/management/unsampledReports

var gaAccount = '1234567';
var gaProperty = 'UA-1234567-12';
var gaView = '987654321';

function insertUnsampledReport() {
  
  var resource = {
    'title': 'appsscript.it - sessioni mensili sito ita gen 2018',
    'start-date': '2018-01-01',
    'end-date': '2018-01-31',
    'metrics': 'ga:sessions',
    'segment': 'sessions::condition::ga:pagePath=~/it/'
  };
  
  var unsampled_report_id = '';
  try {
    var request = Analytics.Management.UnsampledReports.insert(resource, gaAccount, gaProperty, gaView);
  } catch (error) {
    Logger.log(error.message);
    return;
  }
  unsampled_report_id = request.id; // ID del report in CSV

  var cache = CacheService.getScriptCache();
  cache.put("unsampled_report_id", unsampled_report_id, 7200); // cache per 2 ore
  
}

function getUnsampledReport() {
  
  var cache = CacheService.getScriptCache();
  var unsampled_report_id = cache.get("unsampled_report_id");
  
  var request = Analytics.Management.UnsampledReports.get(gaAccount, gaProperty, gaView, unsampled_report_id);

  var request_status = request.status;
  if (request_status == "COMPLETED") {
    var unsampled_report_drive_id = request.driveDownloadDetails.documentId;
    var file = DriveApp.getFileById(unsampled_report_drive_id);
    var csv_string = file.getBlob().getDataAsString();
    var result = Utilities.parseCsv(csv_string);
  } 

}

La generazione di un report non campionato (tramite la funzione: insertUnsampledReport()) fa uso del metodo insert, delle Unsampled Reports API, che prevede il passaggio di 4 parametri: il contenuto della richiesta per la creazione del report non campionato e le informazioni di Account, Proprietà e Vista di Google Analytics per il quale (e nel quale) generarlo.

I Parametri previsti per la body request sono:

title: il titolo del report non campionato
start-date: la data di inizio report
end-date: la data di fine report
metrics: le metriche da richiedere
segment: il tipo di segmento da applicare ai dati (opzionale)
dimensions: le metriche da richiedere (opzionale)
filters: i filtri da applicare ai dati (opzionale)

Un esempio di riposta alla chiamata di tale metodo è il seguente:

  // Esempio di risposta all'API Analytics.Management.UnsampledReports.insert:

  {
       "id":"A4rUJpI7SjDGn_yhFnhsTA"
       "kind":"analytics#unsampledReport",
       "created":"2018-02-07T16:12:24.236Z",
       "accountId":"1234567",
       "profileId":"987654321",
       "created":"2018-02-07T16:12:24.236Z",
       "status":"PENDING",
       "title":"appsscript.it - sessioni mensili sito ita gen 2018",
       "webPropertyId":"UA-1234567-12",
       "selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/1234567/webproperties/UA-1234567-12/profiles/987654321/unsampledReports/A4rUJpI7SjDGn_yhFnhsTA"
  }

Dove id è il riferimento univoco del CSV che sarà generato. Questo valore servirà successivamente per il recupero del report pertanto per tenerne nota ne ho previsto il salvataggio nella Cache (per maggiori informazioni sul Servizio Cache di Apps Script rimando al tutorial 'Memorizzare le risorse nella Cache e condividerle tra un'esecuzione e l'altra').

In conseguenza a quanto appena descritto, un altro valore di interesse è quello dello status, che al momento della richiesta di generazione ha valore PENDING in quanto la richiesta è in fase di elaborazione (di conseguenza l'effettivo report al momento non esiste ancora).

Questo è il motivo per il quale la funzione di generazione report e quella di recupero informazioni sono distinte.

Dopo un variabile lasso di tempo è possibile provare a recuperare i dettagli del report generato tramite il metodo get delle Unsampled Report API (chiamando la funzione: getUnsampledReport()) che prevede il passaggio di 4 parametri: le informazioni di Account, Proprietà e Vista di Google Analytics dove andare a recuperare il report e l'id del report (nel caso dell'esempio, recuperato dalla Cache).

Un esempio di riposta alla chiamata di tale metodo è il seguente:

 // Esempio di risposta all'API Analytics.Management.UnsampledReports.get:

  {
       "driveDownloadDetails":{"documentId":"0Bzfik5H9WqsLK3jsuVM2s5SrqPO"},
       "id":"A4rUJpI7SjDGn_yhFnhsTA",
       "kind":"analytics#unsampledReport",
       "created":"2018-02-07T16:12:24.236Z",
       "accountId":"1234567",
       "profileId":"987654321",
       "updated":"2018-02-07T16:32:22.221Z",
       "status":"COMPLETED",
       "title":"appsscript.it - sessioni mensili sito ita gen 2018",
       "webPropertyId":"UA-1234567-12",
       "selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/1234567/webproperties/UA-1234567-12/profiles/987654321/unsampledReports/A4rUJpI7SjDGn_yhFnhsTA",
       "downloadType":"GOOGLE_DRIVE"
  }

In questa fase assume piena importanza il valore di status che, affinché le operazioni successive vadano a buon fine, dovrà essere necessariamente COMPLETED.

ATTENZIONE: in caso di automatizzazione di molti report un consiglio è quello di prevedere un lasso di tempo, tra la generazione dei CSV e l'avvio della funzione per il loro recupero, di circa 1 ora o poco più, al fine di dare il tempo ad Analytics di completare la generazione del report non campionato rendendolo disponibile.
Questa precauzione, a differenza di un più spontaneo controllo continuo sullo status dei report, può essere utile a tenere sotto controllo i limiti di esecuzione giornaliera degli script di Apps Script (Quotas for Google Services) nonché quelli di scrittura e lettura relativa alle API dei report non campionati (Limits and Quotas).

Nel caso in cui lo status risulti FAILED è probabile che ci siano incongruenze nella richiesta o che siano stati superati i limiti di quota.

Una volta che lo status del report risulta COMPLETED sarà possibile recuperare il CSV su Google Drive dell'utente che lo ha generato tramite il relativo id presente nella risposta alla chiamata all'API (il parametro documentId all'interno dell'oggetto di driveDownloadDetails) ed elaborarne il contenuto secondo le proprie esigenze.

L'immagine seguente, Fig. 1, mostra il contenuto di un report non campionato in formato CSV, con le informazioni utilizzate nell'esempio di questo tutorial, recuperato da Drive con il nome che gli è stato precedentemente definito:

Fig. 1. - Report non campionato in formato CSV generato tramite API con Google Apps Script

Nota: passati 6 mesi dal giorno della generazione del rapporto non campionato, non sarà più possibile averne disponibilità nell'interfaccia di Google Analytics 360 (ovviamente è possibile fare una nuova richiesta per lo stesso rapporto), tuttavia il relativo file di esportazione in formato CSV, inviato alla cartella di Google Drive dell'utente che ne ha fatto richiesta, sarà sempre presente.