Guida per gli sviluppatori

Questo documento descrive come utilizzare l'API Real Time Reporting per ottenere dati di Google Analytics.

Introduzione

L'API Real Time Reporting ti consente di segnalare le attività in corso nella tua proprietà in questo momento. Per accedere ai dati in tempo reale, crea una query che specifica una vista (profilo) e almeno una metrica. Puoi anche fornire parametri di query aggiuntivi come dimensioni e filtri per perfezionare la query. Questa query viene inviata all'API Real Time Reporting, che restituisce i dati sotto forma di tabella.

Se non hai mai utilizzato l'API, leggi la panoramica dell'API Real Time Reporting per un'introduzione all'API Real Time Reporting e ai dati che fornisce.

Prerequisito

Prima di utilizzare l'API Real Time Reporting per ottenere i dati di Google Analytics:

  • Leggi la pagina relativa alle librerie client per un elenco completo delle librerie client specifiche dei linguaggi di programmazione che funzionano con l'API.
  • Leggi la guida di riferimento per scoprire come utilizzare l'API da sola (senza utilizzare una libreria client) per ottenere i dati di Google Analytics.

Ogni libreria client fornisce un singolo oggetto del servizio di analisi per accedere a tutti i dati dell'API Real Time Reporting. Per creare un oggetto di servizio:

  1. Registra la tua applicazione nella console API di Google.
  2. Autorizza l'accesso ai dati di Google Analytics.
  3. Creare un oggetto di servizio Analytics.

Se non hai completato questi passaggi, ti invitiamo a leggere il tutorial sull'API di Google Analytics, che illustra i passaggi iniziali per la creazione di un'applicazione API di Google Analytics. Dopodiché sai come utilizzare l'API per ottenere i dati di Google Analytics.

Utilizzo dell'API Real Time Reporting

Per utilizzare l'API Real Time Reporting, un'applicazione:

  1. Esegue una query sull'API Real Time Reporting.
  2. Gestisce la risposta dell'API.

Esecuzione di query sull'API Real Time Reporting

L'oggetto del servizio di analisi fornisce un metodo per creare una query dell'API Real Time Reporting. Per maggiori dettagli sui parametri di query e sui dati disponibili per l'API, leggi:

Dopo aver definito una query, chiama il relativo metodo execute per inviarla ai server di Google Analytics.

Gestione della risposta dell'API

Se una query all'API Real Time Reporting ha esito positivo, l'API restituisce i dati richiesti come parte di una risorsa di dati in tempo reale. Per maggiori dettagli sulla struttura e sul formato delle risposte dell'API, consulta Riferimento API Real Time Reporting.

Se si verificano errori, l'API restituisce un codice di stato specifico e un messaggio che descrive l'errore. Tutte le applicazioni devono rilevare e gestire gli errori. Per un elenco dettagliato degli errori e i suggerimenti per i nuovi tentativi, consulta Risposte di errore .

Esempi di codice

La sezione Esempi nella pagina Dati in tempo reale: get fornisce codice di esempio in vari linguaggi di programmazione per eseguire query sull'API di reporting in tempo reale e gestire la risposta dell'API.

Vincoli di query

Queste sono le limitazioni per le query dell'API Real Time:

  • Se la metrica rt:activeUsers viene inclusa in una query con i seguenti filtri delle dimensioni, sono supportati solo l'operatore AND e il tipo di corrispondenza di uguaglianza (==).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Poiché al momento la metrica rt:activeUsers recupera solo il numero di utenti attivi sul sito, non utilizzare rt:minutesAgo con rt:activeUsers. Vale a dire che rt:activeUsers implica che rt:minutesAgo è 0.

  • I filtri delle metriche non sono supportati.
  • Il parametro fields non è supportato.

Gestione delle quote

Come descritto in Limiti e quota, l'API Real Time Reporting include quote giornaliere condivise con altre API di Google Analytics. Se esegui il polling dell'API Real Time Reporting a intervalli brevi, raggiungi i limiti di quota giornalieri molto rapidamente. In questo caso, anche le richieste di altre API Google Analytics smettono di funzionare fino a quando la quota non viene aggiornata.

Di seguito sono riportate alcune implementazioni di esempio che potrebbero utilizzare molto rapidamente la quota:

  • Hai più dashboard in tempo reale che eseguono query sui dati per una singola vista (profilo) Google Analytics a intervalli molto brevi su base giornaliera.
  • Hai una proprietà con molti utenti e hai implementato un widget in tempo reale. Ogni volta che il widget viene mostrato a un utente, esegui una query direttamente su Google Analytics, anziché utilizzare una cache.

Per ridurre al minimo l'utilizzo della quota e gestirlo in modo efficiente:

  • Implementa la memorizzazione nella cache lato server. Quando più utenti fanno una richiesta per gli stessi dati in tempo reale, devi restituire una risposta memorizzata nella cache invece di eseguire una query direttamente all'API Real Time Reporting per la richiesta di ogni utente. Quindi, aggiorna periodicamente la cache con i dati in tempo reale più recenti a intervalli di aggiornamento ragionevoli per evitare di superare i limiti di quota giornalieri.
  • Combina più query specificando dimensioni aggiuntive e analizza la risposta sul lato server o client.
  • Aumenta l'intervallo di tempo durante il quale richiedi i dati in tempo reale.

Esempio: calcolo di un intervallo di aggiornamento

Se prevedi di effettuare richieste regolari per dati in tempo reale, devi selezionare un intervallo di aggiornamento ragionevole in base all'utilizzo previsto.

Ad esempio, una singola vista (profilo) Google Analytics ha un limite di quota giornaliero di 10.000 richieste al giorno. Se nell'arco di un solo giorno prevedi di effettuare 6000 query all'API di reporting principale per una singola vista (profilo), avrai una quota di 4000 richieste rimanenti per quella vista (profilo).

Supponiamo che tu decida di utilizzare l'API Real Time Reporting per implementare tre dashboard in tempo reale che eseguono query tutto il giorno sui dati in tempo reale provenienti dalla stessa vista (profilo). Ogni dashboard può eseguire circa 1333 query al giorno (4000 query / 3 dashboard). Ci sono 86.400 secondi in un giorno. Pertanto, l'intervallo di aggiornamento per ogni dashboard deve essere superiore a 65 secondi (86.400 / 1333) in modo che il numero totale di richieste giornaliere per la vista (profilo) sia inferiore al limite giornaliero di 4000.