Accesso automatico ai dati di Google Analytics in Fogli Google

Nick Mihailovski, Team API di Google Analytics – Agosto 2012

Questo tutorial descrive come accedere alle API di gestione e di reporting principali in Fogli Google utilizzando Apps Script.


Introduzione

Puoi utilizzare l'API Google Analytics e Google Apps Script per accedere ai dati di Google Analytics da Fogli Google. Si tratta di una funzionalità potente perché ti consente di utilizzare tutte le fantastiche funzionalità di Fogli Google con i tuoi dati di analisi, come gli strumenti di condivisione, collaborazione, creazione di grafici e visualizzazione semplici.

Questo tutorial illustra il codice necessario per accedere ai dati di Google Analytics in Fogli Google utilizzando Google Apps Script.

Panoramica

Questo tutorial ti mostrerà come registrarti e configurare l'ambiente Apps Script per l'utilizzo dell'API Google Analytics. Dopo la configurazione, il tutorial illustra come recuperare un ID vista (profilo) per l'utente autorizzato utilizzando l' API di gestione. Quindi, come utilizzare l'ID vista (profilo) per eseguire una query sull' API Core Reporting al fine di recuperare le 250 parole chiave per la ricerca da dispositivi mobili più popolari da Google. Infine, i risultati verranno inseriti in un foglio di lavoro Google. Una volta ottenuti i dati, il tutorial illustra anche come automatizzare il recupero dei dati.

Quando crei un'applicazione utilizzando l'API Google Analytics e Apps Script, in genere devi svolgere i seguenti passaggi:

  • Abilitare le API Google Analytics in Fogli Google
  • Utilizza le API di Google Analytics

Analizziamo in dettaglio ogni passaggio.

Attiva l'API Google Analytics in Apps Script

Per attivare l'accesso ai dati di Google Analytics da Fogli Google, segui questi passaggi:

  1. Creare un file di Fogli Google. Scegli un nome accattivante.
  2. Crea un nuovo script di Google Apps.
    1. Nel menu, vai a Estensioni > Apps Script.
    2. Se viene visualizzato un menu, fai clic su Progetto vuoto.
    3. Assegna un nome al progetto. Assicurati che abbia un nome accattivante.

Una volta creato un nuovo script, devi abilitare il servizio Google Analytics.

  1. Nell'editor di script, seleziona Risorse > Servizi Google avanzati...
  2. Nella finestra di dialogo visualizzata, fai clic sull'opzione on/off accanto all'API Google Analytics.
  3. Nella parte inferiore della finestra di dialogo, fai clic sul link di Google Developers Console.
  4. Nella nuova console, fai di nuovo clic sull'opzione on/off accanto all'API Google Analytics. Dopo l'abilitazione, verrà mostrato in cima alla pagina.
  5. Torna all'editor di script e fai clic su OK nella finestra di dialogo.

Dovresti visualizzare una piccola finestra di dialogo gialla in cui ti viene comunicato che hai aggiunto correttamente un nuovo servizio delle API di Google allo script. Ora puoi iniziare a scrivere il tuo primo script.

Utilizza l'API di Google Analytics

Lo script di questo tutorial eseguirà una query nell'API Google Analytics per le 250 parole chiave principali per la ricerca mobile di Google, quindi genererà i risultati in Fogli Google. A questo scopo, lo script seguirà questi passaggi:

  • Recupera la prima visualizzazione (profilo) dell'utente autorizzato.
  • Eseguire una query sull'API Core Reporting per i dati.
  • Inserisci i dati in un foglio di lavoro.

Aggiungi la funzione seguente al progetto vuoto.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

Nel codice riportato sopra, viene utilizzato un blocco try...catch per gestire eventuali errori dell'API. Se si verificano errori, l'esecuzione del programma verrà interrotta e l'errore verrà visualizzato in una finestra di messaggio. Nel blocco try, viene utilizzata una funzione per eseguire ciascuno dei passaggi eseguiti dallo script. Ora aggiungiamo il codice per ognuna di queste funzioni.

Recupera la prima visualizzazione (profilo) dell'utente autorizzato

In Google Analytics, ogni report appartiene a una vista (profilo) ed è identificato da un ID vista (profilo). Di conseguenza, quando specifichi una query per i dati di un report, devi specificare anche l'ID vista (profilo) della vista (profilo) da cui vuoi recuperare i dati.

L' API di gestione di Google Analytics fornisce l'accesso a tutti gli account, le proprietà web e le entità vista (profilo) che appartengono a un utente. Ognuna di queste entità appartiene a una gerarchia e puoi attraversarla in modo programmatico per recuperare un ID vista (profilo) per l'utente autorizzato.

La seconda funzione che scriveremo attraverserà la gerarchia dell'API di gestione e restituirà la prima visualizzazione (profilo) dell'utente. Copia e incolla il seguente codice nel tuo progetto Apps Script:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

In questa funzione, viene eseguita una query sulla raccolta degli account utilizzando il metodo Analytics.Management.Accounts.list. Se l'utente autorizzato dispone di account Google Analytics, viene recuperato l'ID del primo account. Successivamente, viene eseguita una query sulla raccolta delle proprietà web chiamando il metodo Analytics.Management.Webproperties.list e passando il metodo tramite l'ID account recuperato nel passaggio precedente. Se esistono proprietà web, viene infine eseguita una query sulla raccolta della vista (profilo) utilizzando il metodo Analytics.Management.Profiles.list. Sia l'ID account sia gli ID proprietà web vengono trasmessi come parametri a questo metodo. Se esistono viste (profili), viene restituita la prima vista (profilo).

Se in qualsiasi momento si verifica un errore dell'API o se la risposta dell'API non contiene risultati, viene visualizzato un errore con un messaggio che indica che non sono stati trovati risultati. Il blocco catch nella funzione runDemo riportata sopra rileverà questo errore e stamperà il messaggio all'utente.

Una volta restituito lo script, può eseguire query sui dati dei report.

Eseguire una query sull'API Core Reporting per i dati.

Una volta ottenuto un ID vista (profilo), utilizza l'API Core Reporting per eseguire query sui dati del report di Google Analytics. In questa sezione imparerai a eseguire query su questa API utilizzando Apps Script.

Aggiungi il seguente codice al tuo progetto Apps Script:

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

La prima parte del codice crea una query dell'API Core Reporting utilizzando il metodo Analytics.Data.Ga.get. Il metodo accetta un gruppo di parametri che specificano il tipo di report da recuperare. Ogni query dell'API Core Reporting è composta da un insieme di parametri obbligatori e facoltativi. I parametri obbligatori vengono passati al metodo come parametri, mentre i parametri facoltativi vengono trasmessi come oggetto.

Il parametro table ID è obbligatorio e viene formato combinando il prefisso ga: con l'ID vista (profilo). Il codice crea l'ID tabella utilizzando l'ID vista (profilo) recuperato nel passaggio precedente. Sono obbligatorie anche le date di inizio e fine, e specificare l'intervallo di date dei dati da recuperare. Entrambi sono calcolati in base alla data odierna utilizzando la funzione getLastNdays. Infine, tutti i parametri facoltativi vengono passati alla funzione utilizzando l'oggetto optArgs.

Quando il metodo Analytics.Data.Ga.get viene eseguito, viene effettuata una richiesta all'API di reporting principale. Se si verifica un errore, viene rilevato nel blocco try...catch definito nel metodo runDemo esterno. Se la richiesta ha esito positivo, vengono restituiti i risultati.

Inserisci i dati in un foglio di lavoro

Il passaggio finale del nostro script consiste nell'eseguire l'output dei risultati dall'API di reporting principale in Fogli Google. Questo metodo funziona con il metodo outputToSpreadsheet. Aggiungi il seguente codice al tuo progetto:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

Questa funzione inserisce prima un nuovo foglio nel foglio di lavoro attivo. Successivamente, inserisce nel foglio tutte le intestazioni e i dati dei report. Per ulteriori suggerimenti su come inserire dati in Fogli Google, leggi l'articolo Scrittura di dati da oggetti JavaScript in un foglio di lavoro nel tutorial sull'archiviazione di dati in fogli di lavoro.

Esegui lo script

Dopo aver aggiunto tutto il codice al progetto, puoi eseguirlo.

  • Nella barra degli strumenti dell'editor di script, seleziona runDemo nel menu a discesa Seleziona funzione.
  • Quindi, fai clic sul pulsante play.

La prima volta che esegui questa operazione, viene visualizzata una finestra popup che richiede l'autorizzazione dello script ad accedere ai dati del tuo account Google Analytics.

Fai clic su Autorizza.

Dopo aver fatto clic, si aprirà una nuova pagina ospitata su google.com che ti chiederà di concedere a questo script l'accesso ai tuoi dati. Dopo aver fatto clic su Consenti, si aprirà una pagina di conferma. A questo punto, lo script potrà accedere ai dati di Google Analytics e continuare a essere eseguito.

Al termine dell'esecuzione dello script, fai clic sulla finestra con Fogli Google. Dovresti vedere tutti i dati delle parole chiave restituiti dall'API o una casella di messaggio con un messaggio di errore.

Automatizza lo script

A questo punto dovresti avere uno script che esegue query sull'API di Google Analytics. Ora ti consigliamo di automatizzare lo script per recuperare nuovi dati ogni notte. Apps Script semplifica molto l'automazione con la funzionalità triggers.

Per automatizzare questo script, segui questi passaggi:

  • Nella barra degli strumenti dell'editor di script, fai clic su Resources -> All your triggers....
  • Fai clic su Add a new trigger. Viene visualizzata la finestra di dialogo degli attivatori.
  • Configura il trigger per eseguire il metodo runDemo ogni notte
    • Il menu a discesa Run deve essere impostato su: runDemo
    • Il menu a discesa Events deve essere impostato su: Time-driven, Day timer e Midnight to 1am.

Una volta configurato, questo script verrà eseguito ogni notte e ti fornirà dati aggiornati la mattina.

Se si verificano errori durante la notte, ti verrà inviata una notifica. Apps Script ti consente anche di inviare un'email di avviso in caso di errori. Per configurare questa funzionalità, fai clic sul link notifications nella finestra di dialogo degli attivatori. Viene visualizzata una nuova finestra di dialogo che ti consente di configurare l'email a cui inviare gli errori.

Conclusione

hai eseguito correttamente la registrazione e l'autorizzazione dell'accesso al tuo script. Hai chiesto più volte all'API di gestione di recuperare un ID vista (profilo). Poi hai utilizzato l'ID vista (profilo) per eseguire una query sull'API Core Reporting al fine di recuperare i dati e riprodurli in Fogli Google.

Utilizzando le tecniche descritte nel tutorial, potrai effettuare analisi più complesse, ottenere informazioni più approfondite, creare dashboard personalizzate e ridurre molto il tempo di esecuzione di report manuali.

Di seguito sono riportati altri tutorial interessanti che potrebbero esserti utili per sfruttare al meglio l'API Google Analytics e Google Apps Script: