Guía para desarrolladores

En este documento se describe cómo usar la API de informes en tiempo real para obtener datos de Google Analytics.

Introducción

La API de informes en tiempo real permite elaborar informes sobre la actividad que se está produciendo en tu propiedad. Para acceder a los datos en tiempo real, puedes crear una consulta en la que se especifique una vista (perfil) y, al menos, una métrica. También puedes incluir parámetros de consulta adicionales, como dimensiones y filtros, para definir mejor la consulta. Esta consulta se envía a la API de informes en tiempo real, que devuelve los datos en formato de tabla.

Si es la primera vez que usas la API, consulta en Descripción general de la API de informes en tiempo real una introducción a la finalidad de la API y los datos que proporciona.

Requisito previo

Antes de usar la API de informes en tiempo real para obtener datos de Google Analytics:

  • Consulta la página de bibliotecas de cliente para obtener una lista completa de las bibliotecas de cliente de cada lenguaje de programación que funcionan con la API.
  • Consulta la Guía de referencia a fin de saber cómo usar la API sola (sin ninguna biblioteca de cliente) para obtener datos de Google.

Cada biblioteca de cliente proporciona un solo objeto de servicio analytics para acceder a todos los datos de la API de informes en tiempo real. Para crear un objeto de servicio:

  1. Registra tu aplicación en la consola de la API de Google.
  2. Autoriza el acceso a los datos de Google Analytics.
  3. Crea un objeto de servicio analytics.

Si no has completado estos pasos, no continúes y lee Tutorial: Hello Analytics API, en el que se te guiará por los pasos para compilar una aplicación de la API de Google Analytics. Cuando lo hayas leído, sabrás cómo usar la API para obtener datos de Google Analytics.

Usar la API de informes en tiempo real

Para usar la API de informes en tiempo real, una aplicación debe:

  1. Consultar la API de informes en tiempo real
  2. Gestionar la respuesta de la API

Consultar la API de informes en tiempo real

El objeto de servicio analytics ofrece un método para crear una consulta de la API de informes en tiempo real. Para obtener información sobre los parámetros de consulta y los datos disponibles mediante la API, lee la documentación siguiente:

Una vez que hayas definido una consulta, llama a su método execute para enviarla a los servidores de Google Analytics.

Gestionar la respuesta de la API

Si una consulta a la API de informes en tiempo real se realiza correctamente, la API devolverá los datos solicitados como parte de un recurso de datos en tiempo real. Consulta la referencia de la API de informes en tiempo real para obtener información sobre la estructura y el formato de la respuesta de la API.

Si se producen errores, la API devolverá un código de estado específico y un mensaje en el que se describe el error. Todas las aplicaciones deben interceptar y gestionar correctamente los errores. Consulta en Respuestas de error una lista detallada de errores y las recomendaciones de reintento.

Ejemplos de código

En la sección Ejemplos de la página Datos en tiempo real: get se ofrece código de muestra en los distintos lenguajes de programación para realizar una consulta a la API de informes en tiempo real y gestionar la respuesta de dicha API.

Restricciones de consulta

Estas son las restricciones que presentan las consultas de la API de informes en tiempo real:

  • Si se incluye la métrica rt:activeUsers en una consulta con los siguientes filtros de dimensión, solo se admite el operador AND y el tipo de concordancia de igualdad (==).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Dado que la métrica rt:activeUsers solo recupera el número de usuarios activos en el sitio en el momento de realizar la consulta, no es posible usar rt:minutesAgo con rt:activeUsers. Es decir, rt:activeUsers implica que rt:minutesAgo es 0.

  • No se admiten los filtros de métrica.
  • No se admite el parámetro fields.

Administración de la cuota

Tal como se describe en Límites y cuotas, hay cuotas diarias en la API de informes en tiempo real que se comparten con otras API de Google Analytics. Si sondeas la API de informes en tiempo real a intervalos breves, se pueden alcanzar los límites de cuota diaria muy rápidamente. En este caso, las solicitudes de otras API de Google Analytics también dejarán de funcionar hasta que se actualice la cuota.

A continuación te indicamos algunas implementaciones de ejemplo que pueden agotar la cuota muy rápidamente:

  • Tienes varios paneles en tiempo real que consultan datos de una sola vista (perfil) de Google Analytics a intervalos muy breves cada día.
  • Tienes una propiedad con muchos usuarios y has implementado un widget en tiempo real. Cada vez que el widget se muestra a un usuario, se consulta a Google Analytics directamente en vez de usar una memoria caché.

Para minimizar el uso de la cuota y administrarla de forma eficiente:

  • Implementa el almacenamiento en caché en el servidor. Cuando varios usuarios realizan una solicitud de los mismos datos en tiempo real, debes devolver una respuesta almacenada en caché en vez de consultar directamente a la API de informes en tiempo real en cada solicitud. Después, actualiza la memoria caché periódicamente con los datos en tiempo real más recientes a un intervalo de actualización razonable que te permita estar dentro de los límites diarios del uso previsto.
  • Combina varias consultas especificando dimensiones adicionales y analizando la respuesta en el servidor o en el cliente.
  • Aumenta el intervalo de tiempo que utilizas para solicitar datos en tiempo real.

Ejemplo: calcular un intervalo de actualización

Si prevés realizar solicitudes periódicas de los datos en tiempo real, debes seleccionar un intervalo de actualización razonable según el uso previsto.

Por ejemplo, una vista (perfil) de Google Analytics tiene un límite de cuota diario de 10.000 solicitudes al día. En un solo día, si prevés realizar 6000 consultas a la API de informes centrales para una sola vista (perfil), te quedarán 4000 solicitudes para dicha vista.

Supongamos que decides usar la API de informes en tiempo real para implementar 3 paneles en tiempo real que se ejecutan todo el día a fin de realizar las consultas de datos en tiempo real en la misma vista (perfil). Cada panel puede realizar 1333 consultas al día (4000 consultas/3 paneles) aproximadamente. Un día tiene 86.400 segundos. Por consiguiente, el intervalo de actualización de cada panel debe ser superior a 65 segundos (86.400/1333) para que el total de solicitudes diarias de la nueva vista (perfil) sea inferior al límite diario de 4000.