API de informes centrales: autorización

En este documento se describe cómo una aplicación puede obtener autorización para realizar solicitudes a la API de informes centrales.

Autorizar solicitudes

Para que los usuarios puedan ver la información de su cuenta en el sitio web de Google Analytics, primero deben iniciar sesión con una cuenta de Google. Del mismo modo, cuando los usuarios acceden por primera vez a tu aplicación, deben concederle autorización para que acceda a sus datos.

Cada autorización que envía tu aplicación a la API de Analytics debe incluir un token de autorización. El token también identifica tu aplicación en Google.

Acerca de los protocolos de autorización

Tu aplicación debe utilizar OAuth 2.0 para autorizar las solicitudes. No se admite ningún otro protocolo de autorización. Si tu aplicación usa el inicio de sesión de Google, algunos aspectos de la autorización se gestionan automáticamente.

Autorizar solicitudes con OAuth 2.0

Todas las solicitudes a la API de Analytics deben estar autorizadas por un usuario autenticado.

Los detalles del proceso de autorización para OAuth 2.0, o "flujo", varían ligeramente dependiendo del tipo de aplicación que estés creando. El siguiente proceso general se aplica a todos los tipos de aplicación:

  1. Cuando hayas creado tu aplicación, regístrala utilizando Google Developers Console. A continuación, Google te proporcionará la información que necesitarás posteriormente, como un ID de cliente y un secreto de cliente.
  2. Activa la API de Analytics en Google Developers Console (si no aparece en la consola, sáltate este paso).
  3. Cuando tu aplicación deba acceder a los datos de usuario, pedirá a Google un determinado ámbito de acceso.
  4. Google muestra una pantalla de consentimiento al usuario pidiéndole su autorización para que la aplicación le solicite algunos datos.
  5. Si el usuario aprueba esta petición, Google ofrecerá a la aplicación un token de acceso de corta duración.
  6. Su aplicación solicita los datos del usuario y adjunta el token de acceso a la solicitud.
  7. Si Google determina que su solicitud y el token son válidos, muestra los datos solicitados.

En algunos flujos se incluyen pasos adicionales, como el uso de tokens de actualización para adquirir nuevos tokens de acceso. Para obtener más información acerca de los flujos de los distintos tipos de aplicaciones, consulta la documentación de OAuth 2.0 de Google.

A continuación se presenta la información de ámbito de OAuth 2.0 de la API de Analytics:

Ámbito Significado
https://www.googleapis.com/auth/analytics.readonly Acceso de solo lectura a la API de Analytics.

Para solicitar el acceso utilizando OAuth 2.0, tu aplicación necesita la información del ámbito, así como la información que proporciona Google durante el registro de la aplicación (como el ID y el secreto de cliente).

Consejo: Las bibliotecas de cliente de las API de Google pueden gestionar algunos de los procesos de autorización automáticamente. Están disponibles para varios lenguajes de programación; consulta la página con bibliotecas y ejemplos para obtener más detalles.

Flujos de OAuth 2.0 habituales

En las directrices siguientes se describen los casos prácticos habituales de determinados flujos de OAuth 2.0:

Servidor web

Este flujo resulta adecuado para el acceso automático, offline o programado de los datos de Google Analytics de un usuario.

Ejemplo:
  • Actualizar automáticamente los paneles de usuario con los datos de Google Analytics más recientes.

En el cliente

Resulta ideal en el caso de que los usuarios interactúen directamente con la aplicación para acceder a sus datos de Google Analytics desde un navegador. Con este flujo no se necesitan funciones en el servidor, pero no se pueden llevar a cabo los informes automatizados, offline o programados.

Ejemplo:

Aplicaciones instaladas

Para aplicaciones que se distribuyen en paquetes y las instala el usuario. Es necesario que la aplicación o el usuario tengan acceso a un navegador para completar el flujo de autenticación.

Ejemplos:
  • Un widget de equipo en un PC o Mac.
  • Un plugin de un sistema de gestión de contenido. La ventaja de este flujo, en relación con el de servidor web o de cliente, reside en que ese puede usar un solo proyecto de Developers Console para la aplicación. De este modo, se pueden elaborar informes consolidados y se simplifica la instalación para los usuarios.

Cuentas de servicio

Útil para el acceso automatizado, offline o programado a los datos de Google Analytics de tu propia cuenta. Por ejemplo, para crear un panel activo de tus propios datos de Google Analytics y compartirlo con otros usuarios.

Debes realizar una serie de pasos a fin de configurar las cuentas de servicio para que funcionen con Google Analytics.

Para empezar a usar la API de Analytics, primero debes crear o seleccionar un proyecto en Google Developers Console y habilitar la API. En este enlace encontrarás una guía del proceso y la API de Analytics se activará automáticamente.

También puedes activar la API de Analytics por tu cuenta en Developers Console haciendo lo siguiente:

  1. Abre la página Credenciales.

En cualquier caso, llegarás a la página Credenciales, donde puedes crear las credenciales de tu proyecto.

Para configurar una nueva cuenta de servicio, realiza las acciones siguientes:

  1. Haz clic en Agregar credenciales > Cuenta de servicio.
  2. Decide si quieres descargar la clave pública/privada de la cuenta de servicio como un archivo P12 estándar o como un archivo JSON que pueda cargar una biblioteca de cliente de la API de Google.

El nuevo par de claves pública/privada se genera y se descarga en el equipo, lo que sirve de copia única de esta clave. Eres responsable de almacenarla de forma segura.

Solución de problemas

Si tienes problemas con la autenticación y aparecen los códigos de estado 401 o 403, puedes realizar una serie de pasos para solucionar los problemas:

El código de estado 401 aparece si tu access_token ha caducado o si utilizas un ámbito erróneo para la API.

El código de estado 403 aparece si el usuario autorizado no tiene acceso a la vista (perfil). Asegúrate de que estás autorizado con el usuario correcto y que tiene la vista (perfil) que has seleccionado.

Espacio de OAuth 2.0. Es una herramienta fantástica que te permite llevar a cabo todo el proceso de autorización mediante una interfaz web. En la herramienta también se muestran todos los encabezados de solicitud HTTP necesarios para realizar una consulta autorizada. Si no consigues que la autorización funcione en tu aplicación, debes probar que lo haga a través del espacio de OAuth 2.0. Después, puedes comparar los encabezados HTTP y enviar una solicitud al espacio sobre qué envía tu aplicación a Google Analytics. Esta comprobación es una forma sencilla de garantizar que aplicas el formato correcto a tus solicitudes.

Espacio de OAuth 1.0. Es similar al espacio de OAuth 2.0, pero para la versión anterior.

Concesión no válida

Si aparece la respuesta de error invalid_grant al intentar utilizar un token de actualización, la causa del error se puede deber a los motivos siguientes:

  1. El reloj de tu servidor no está sincronizado con NTP.
  2. Se ha superado el límite de token de actualización.
    Las aplicaciones pueden solicitar varios tokens de actualización para acceder a una sola cuenta de Google Analytics. Esto resulta útil, por ejemplo, en las situaciones en que un usuario desea instalar una aplicación en varios equipos y acceder a la misma cuenta de Google Analytics. En este caso, se requieren dos tokens de actualización, uno por cada instalación. Cuando el número de tokens de actualización supera el límite, los tokens anteriores dejan de ser válidos. Si la aplicación intenta utilizar un token de actualización invalidado, se devuelve la respuesta de error invalid_grant. El límite para cada par único de cliente OAuth 2.0 y cuenta de Google Analytics es de 25 tokens de actualización (este límite está sujeto a cambios). Si la aplicación sigue solicitando tokens de actualización para el mismo par de cliente y cuenta, se solicita el token número 26, el primer token de actualización que se ha emitido anteriormente deja de ser válido. El token de actualización número 27 que se solicite invalidará el segundo token emitido anteriormente, y así sucesivamente.