Generare report automatici con i dati di Google Analytics in Google Sheets

Tramite Google Apps Script e le API di Google Analytics, in particolare le Management API che permettono di visualizzare e gestirere account, proprietà e viste e le Core Reporting API che consentono di effettuare interrogazioni di dimensioni e metriche per il recupero dei dati, è possibile realizzare report personalizzati con i dati di Google Analytics all'interno degli Spreadsheet.

Il presente scenario non rappresenta certo una novità dato che la documentazione ufficiale di Google, a differenza di altre situazioni in cui propone piccole porzioni di codice al solo scopo di mostrarne la sintassi, offre uno script completo che sfrutta le API appena citate per selezionare una vista all'interno di un account di Google Analytics sulla quale andare ad effettuare un'interrogazione sui dati per riportarli successivamente all'interno di un Google Sheet, non a caso questa pagina della documentazione si chiama 'Automated Access to Google Analytics Data in Google Sheets'.

In questo articolo ho provato a semplificare lo script in questione apportando piccole modifiche in modo da concentrare l'attenzione sulle parti principali commentandole di conseguenza.

Poniamo pertanto di conoscere l'id della vista di nostro interesse, chiamata di seguito profileId, e di voler ottenere uno Spreadsheet con uno script associato (bound-script) che ogni giorno interroga tale vista di Google Analytics per l'ottenimento delle informazioni di sessioni (sessions) e pagine visualizzate (pageviews) distribuita per gruppo di canale (channel grouping) dall'inizio dell'anno in corso fino al giorno precedente a quello dell'esecuzione dello script e che tali dati vengano scritti una volta il giorno in un foglio distinto, nominato adeguatamente in base al range di date interrogato, dello Spreadsheet.

Il codice seguente effettua le operazioni appena descritte.
Per implementare il codice all'interno di uno Spreadsheet è necessario inserirlo nel suo editor di Google Apps Script associato accessibile cliccando sulla voce 'Strumenti -> Editor di script...':

var profileId = '89687386'; // l'id della vista di Google Analytics dalla quale estrarre i dati
var tableId = 'ga:' + profileId;
var startDate = '2018-01-01';
var days_ago = 1; // un giorno in meno rispetto ad oggi (ieri)
var today = new Date();
var before = new Date();
before.setDate(today.getDate() - days_ago);
var endDate = Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd'); // data di ieri nel formato yyyy-MM-dd

function avviaGenerazioneReport() {
  try {
    var results = getReportDataForProfile(profileId);
    outputToSpreadsheet(results);
    
  } catch(error) {
    throw new Error(error.message);
  }
}

function getReportDataForProfile() {
  
  // Dimensioni ed altri parametri opzionali
  var optArgs = {
    'dimensions': 'ga:channelGrouping', // Lista delle dimensioni separate da virgola
    'sort': '-ga:sessions',             // Ordinamento dei risultati in modo decrescente in base alle sessioni
  };
  
  // API per la richiesta del report ad Analytics in base ai valori dei parametri passati
  var results = Analytics.Data.Ga.get(
    tableId,                            // id della tabella composto da 'ga:' + l'id della vista
    startDate,                          // data di inizio report nel formato yyyy-MM-dd
    endDate,                            // data di fine report nel formato yyyy-MM-dd
    'ga:sessions,ga:pageviews',         // Lista delle metriche separate da virgola
    optArgs                             // valori opzionali (dimensions, sort, filters, segment, ...)
  );

  // Se sono presenti risultati dalla chiamata all'API, la funzione li restituisce
  if (results.getRows()) { return results; }

}

function outputToSpreadsheet(results) {
  
  // Inserisce un nuovo foglio nello Spreadsheet principale
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Crea un array con i nomi delle dimensioni e metriche in base all'array di oggetti 'columnHeaders' tramite 'getColumnHeaders()'
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  // Inserisce l'array appena creato come intestazione delle colonne del nuovo foglio dello Spreadsheet
  sheet.getRange(1, 1, 1, headerNames.length).setValues([headerNames]);

  // Inserisce le righe dei risultatipartendo dalla seconda riga del foglio in base all'array di array 'row' tramite 'getRows()'
  sheet.getRange(2, 1, results.getRows().length, headerNames.length).setValues(results.getRows());
  
  // Modifica il nome del foglio dello Spreasheet in un formato del tipo '2018-01-01_2018-02-09'
  // in modo da poter riferire i dati al periodo per il quale sono stati estratti
  sheet.setName(startDate + '_' + endDate);
}

Avviando la funzione avviaGenerazioneReport() (la prima volta, utilizzando le API di Analytics è necessario abilitare l'uso delle API dei Servizi Avanzati di Google nel progetto in questione; nel caso dello script oggetto del presente tutorial l'abilitazione deve essere effettuata per le Google Analytics API) viene costruita la richiesta per interrogare l'API di tipo Core Reporting utilizzando il metodo Analytics.Data.Ga.get che accetta una serie di parametri che permettono di specificare i dettagli del report da recuperare.
Ogni query dell'API Core Reporting consiste in un set di parametri obbligatori e facoltativi (quest'ultimi vengono passati alla funzione come oggetto).

I parametri obbligatori sono: tableId, formato dalla combinazione del prefisso ga: e dell'ID della vista di Analytics (profileId); startdDate ed endDate, la data di inizio e di fine, nel formato yyyy-MM-dd, per definire l'intervallo di date dei dati da recuperare; una o più metriche separate da virgola e, come ultimo parametro, facoltativo, viene passato un oggetto contenente eventuali valori opzionali (dimensions, sort, filters, segment, ...).

La risposta all'interrogazione dell'Analytics.Data.Ga.get() è qualcosa simile alla seguente dove, per il periodo che intercorre dalla data di inizio anno fino al giorno precedente l'esecuzione del file, è stata interrogata l'API per l'ottenimento di un report che mostra il numero di sessioni e di pagine visualizzate distinto per canale ed ordinato in modo decrescente per il numero delle sessioni (per un elenco completo di tutte le dimensioni e metriche disponibili tramite le Core Reporting API rimando alla documentazione ufficiale, Dimensions & Metrics Explorer):

{
  totalsForAllResults={ga:sessions=4186, ga:pageviews=4932},
    totalResults=5,
    columnHeaders=[
      {columnType=DIMENSION, dataType=STRING, name=ga:channelGrouping},
      {columnType=METRIC, dataType=INTEGER, name=ga:sessions},
      {columnType=METRIC, dataType=INTEGER, name=ga:pageviews}
    ],
    profileInfo={profileName=nome della vista, accountId=1234567, profileId=987654321, tableId=ga:987654321, webPropertyId=UA-1234567-12, internalWebPropertyId=8765432},
    itemsPerPage=1000,
    kind=analytics#gaData,
    query={end-date=2018-02-09, max-results=1000, start-index=1, ids=ga:987654321, start-date=2018-01-01, sort=[-ga:sessions], metrics=[ga:sessions, ga:pageviews], dimensions=ga:channelGrouping},
    containsSampledData=false,
    id=https://www.googleapis.com/analytics/v3/data/ga?ids=ga:987654321&dimensions=ga:channelGrouping&metrics=ga:sessions,ga:pageviews&sort=-ga:sessions&start-date=2018-01-01&end-date=2018-02-09,
    rows=[[Organic Search, 3833, 4386], [Direct, 269, 420], [Referral, 43, 59], [Social, 38, 64], [(Other), 3, 3]],
    selfLink=https://www.googleapis.com/analytics/v3/data/ga?ids=ga:987654321&dimensions=ga:channelGrouping&metrics=ga:sessions,ga:pageviews&sort=-ga:sessions&start-date=2018-01-01&end-date=2018-02-09
}

Nel contenuto di tale risposta sono ben visibili, oltre alle informazioni di account, proprietà e vista e quelle della richiesta effettuata, anche i dati che andranno a comporre il report, nel caso specifico visibili all'interno dell'array di array row, valore utilizzato successivamente per verificare la presenza di un contenuto valido nella risposta tramite il metodo getRows().
Un altro modo per conoscere se la risposta contiene risultati è quello di verificare se il valore di totalResults è maggiore di 0.

La funzione successiva che viene chiamata dallo script si chiama outputToSpreadsheet() alla quale viene passato come parametro il risultato appena ottenuto dall'interrogazione della Core Reporting API.
Questa funzione inserisce un nuovo Foglio nello Spreadsheet principale dopodiché crea un array con i nomi delle dimensioni e metriche, in base all'array di oggetti columnHeaders, tramite getColumnHeaders() e lo inserisce nel foglio seguito dalle righe dei risultati (a tal proposito, per ottimizzare la fase di scrittura dei dati in un foglio di Google, può essere utile consultare il tutorial 'Scrivere dati su uno Spreadsheet in modo performante con Google Apps Script'), infine modifica il nome del foglio dello Spreasheet in un formato del tipo '2018-01-01_2018-02-09' in modo da poter riferire i dati al periodo per il quale sono stati effettivamente estratti.

Quello che succede all'interno dello Spreadsheet sarà qualcosa di simile a questo, Fig. 1:

Fig. 1 - Report di Google Analytics in Google Sheets generato automaticamente con Apps Script

Per automatizzare giornalmente il report basterà impostare un trigger nell'editor di script dal menu 'Modifica -> Trigger del progetto corrente' e configurarlo in modo da eseguire la funzione avviaGenerazioneReport() tramite un evento basato sul tempo con timer giornaliero dalle 1:00 alle 2:00, come mostrato nell'immagine seguente, Fig. 2:

Fig. 2 - Trigger per l'esecuzione automatica di una funzione in Apps Script basata sul tempo

Personalmente preferisco non attivarlo subito dalle 00:00 alle 1:00 in modo da assicurarmi di aver lasciato abbastanza tempo a Google Analytics per il riallineamento dei dati in piattaforma, dopo la mezzanotte, per la giornata appena trascorsa.