Guía para desarrolladores

En este documento, se describe cómo usar la API de Real Time Reporting para obtener datos de Google Analytics.

Introducción

La API de Informes en tiempo real te permite informar la actividad que está ocurriendo en tu propiedad en este momento. Para acceder a los datos en tiempo real, crea una consulta que especifique una vista (perfil) y al menos una métrica. También puedes proporcionar parámetros de consulta adicionales, como dimensiones y filtros, para definir mejor tu consulta. Esta consulta se envía a la API de Real Time Reporting que muestra los datos en forma de tabla.

Si es la primera vez que usas la API, lee la Descripción general de la API de Informes en tiempo real para obtener una introducción a la API de Informes en tiempo real y los datos que proporciona.

Requisitos

Antes de usar la API de Real Time Reporting para obtener datos de Google Analytics, haz lo siguiente:

  • Lee la página sobre bibliotecas cliente para obtener una lista completa de las bibliotecas cliente específicas de cada lenguaje de programación que funcionan con la API.
  • Lee la Guía de referencia para aprender a usar solo la API (sin usar una biblioteca cliente) para obtener datos de Google Analytics.

Cada biblioteca cliente proporciona un único objeto de servicio de estadísticas para acceder a todos los datos de la API de Real Time Reporting. Para crear un objeto de servicio, haz lo siguiente:

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

Si no completaste estos pasos, detente y lee el instructivo de la API de Hello Google Analytics, que te guiará por los pasos iniciales para compilar una aplicación con la API de Google Analytics. Luego, ya sabrás cómo usar la API para obtener datos de Google Analytics.

Cómo usar la API de Real Time Reporting

Para usar la API de Real Time Reporting, una aplicación debe hacer lo siguiente:

  1. Consulta la API de Real Time Reporting
  2. Controla la respuesta de la API.

Cómo consultar la API de Informes en tiempo real

El objeto del servicio de estadísticas proporciona un método para crear una consulta de la API de Informes en tiempo real. Si deseas obtener detalles sobre los parámetros de consulta y los datos disponibles para la API, lee lo siguiente:

Después de definir una consulta, llama al método execute para enviar la consulta a los servidores de Google Analytics.

Controla la respuesta de la API

Si una consulta a la API de Real Time Reporting se realiza correctamente, esta muestra 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 detalles sobre la estructura y el formato de las respuestas de la API.

Si se produce algún error, la API muestra un código de estado específico y un mensaje que describe el error. Todas las aplicaciones deben detectar y manejar errores. Consulta Respuestas de error para obtener una lista detallada de los errores y las recomendaciones de reintento.

Ejemplos de código

En la sección Ejemplos de la página Datos en tiempo real: obtener, se proporciona código de muestra en varios lenguajes de programación para consultar la API de Informes en tiempo real y manejar su respuesta.

Restricciones de las consultas

Estas son las restricciones para las consultas de la API en tiempo real:

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

    Debido a que la métrica rt:activeUsers solo recupera la cantidad de usuarios activos en el sitio en este momento, no uses rt:minutesAgo con rt:activeUsers. Es decir, rt:activeUsers implica que rt:minutesAgo es 0.

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

Administración de la cuota

Como se describe en Límites y cuotas, la API de Real Time Reporting tiene cuotas diarias que se comparten con otras APIs de Google Analytics. Si sondeas la API de Informes en tiempo real a intervalos cortos, alcanzarás los límites de la cuota diaria con mucha rapidez. Cuando eso sucede, las solicitudes de otras APIs de Google Analytics también dejan de funcionar hasta que se actualice la cuota.

Estas son algunas implementaciones de ejemplo que pueden agotador la cuota muy rápido:

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

Sigue estos pasos para minimizar el uso de la cuota y administrarlo de manera eficiente:

  • Implementa el almacenamiento en caché del servidor. Cuando varios usuarios realizan una solicitud para los mismos datos en tiempo real, debes mostrar una respuesta almacenada en caché en lugar de consultar directamente la API de Informes en tiempo real para cada solicitud de usuario. Luego, actualiza la caché de forma periódica con los datos en tiempo real más recientes, a un intervalo de actualización razonable, para evitar exceder los límites de la cuota diaria.
  • Para combinar varias consultas, especifica dimensiones adicionales y analiza la respuesta en el servidor o el cliente.
  • Aumenta el intervalo en el que solicitas datos en tiempo real.

Ejemplo: Cómo calcular un intervalo de actualización

Si esperas realizar solicitudes regulares de datos en tiempo real, debes seleccionar un intervalo de actualización razonable en función del uso esperado.

Por ejemplo, una sola vista (perfil) de Google Analytics tiene un límite de cuota diario de 10,000 solicitudes por día. En un solo día, si esperas realizar 6,000 consultas a la API de Core Reporting para una sola vista (perfil), tendrás una cuota de 4,000 solicitudes restantes para esa vista (perfil).

Supongamos que decides usar la API de Real Time Reporting para implementar 3 paneles en tiempo real que ejecutan consultas durante todo el día de datos en tiempo real desde la misma vista (perfil). Cada panel puede realizar aproximadamente 1,333 consultas por día (4,000 consultas / 3 paneles). Hay 86,400 segundos en un día. Por lo tanto, el intervalo de actualización de cada panel debe ser superior a 65 segundos (86,400 / 1,333) para que la cantidad total de solicitudes diarias de la vista (perfil) sea inferior al límite diario de 4,000.