API de informes centrales: autorización

En esta guía se describe cómo una aplicación autoriza solicitudes a la API de informes centrales.

Autorizar solicitudes

Para que los usuarios puedan ver la información de sus cuentas en el sitio web de Google Analytics, primero deben iniciar sesión en sus cuentas 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 solicitud 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 las debe autorizar un usuario autenticado.

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

  1. Cuando crees tu aplicación, debes registrarla con la consola de APIs de Google. A continuación, Google te proporciona la información que necesitarás posteriormente, como un ID y un secreto de cliente.
  2. Activa la API de Analytics en la consola de APIs de Google. Si la API no aparece en la lista de la consola de APIs, sáltate este paso.
  3. Cuando tu aplicación necesita acceder a los datos del usuario, esta solicita a Google un determinado permiso de acceso.
  4. Google muestra una pantalla de consentimiento al usuario pidiéndole su autorización para que la aplicación solicite algunos de sus datos.
  5. Si el usuario aprueba esta petición, Google proporciona a la aplicación un token de acceso de corta duración.
  6. Tu aplicación solicita los datos del usuario y adjunta el token de acceso a la solicitud.
  7. Si Google determina que tu 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.

Este es el permiso de OAuth 2.0 con respecto a la API de Analytics:

Permiso 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 el dato del permiso, 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 automáticamente algunos de los procesos de autorización. Se pueden usar con varios lenguajes de programación; consulta la página con bibliotecas y ejemplos para obtener más detalles.

Flujos de OAuth 2.0 habituales

A continuación, se enumeran los casos prácticos habituales de determinados flujos de OAuth 2.0:

Servidor web

Este flujo resulta adecuado para el acceso automático, sin conexión o programado a los datos de Google Analytics de un usuario.

Ejemplo:

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

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 elaborar informes automatizados, sin conexión ni programados.

Ejemplo:

Aplicaciones instaladas

Este flujo es para aplicaciones que se distribuyen en paquetes y que 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 ordenador en un PC o Mac.
  • Un complemento de un sistema de gestión de contenido. La ventaja de este flujo, en relación con el de servidor web o de cliente, es que se puede usar un solo proyecto de la consola de APIs para la aplicación. De este modo, se pueden elaborar informes consolidados y a los usuarios se les facilita la instalación.

Cuentas de servicio

Las cuentas de servicio son útiles para el acceso automatizado, sin conexión o programado a los datos de Google Analytics de tu propia cuenta. Por ejemplo, para crear un panel de control en directo con tus propios datos de Google Analytics y compartirlo con otros usuarios.

Para empezar a usar la API de Analytics, primero debes utilizar la herramienta de configuración, que te guiará por los pasos necesarios para crear un proyecto en la consola de APIs de Google, habilitar la API y crear las credenciales.

Para crear una cuenta de servicio, sigue estos pasos:

  1. Haz clic en Crear credenciales > Clave de cuenta de servicio.
  2. Decide si quieres descargar el par de claves pública/privada de la cuenta de servicio como un archivo P12 estándar o como un archivo JSON que se pueda cargar con una biblioteca de cliente de APIs de Google.

Se genera el par de claves pública/privada y se descarga en el equipo, lo que sirve de copia única de esta clave. Es responsabilidad tuya almacenarla de forma segura.

Solucionar problemas

No se otorgará la autorización en los casos siguientes:

  • Se muestra el código de estado 401 si tu access_token ha caducado o si utilizas un permiso erróneo para la API.

  • Se muestra el código de estado 403 si el usuario autorizado no tiene acceso a la vista (perfil). Asegúrate de tener la autorización del usuario correcto y que este tenga la vista (perfil) que has seleccionado.

OAuth 2.0 Playground

Esta herramienta 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 solicitudes autorizadas. Si no consigues que la autorización funcione en tu aplicación, debes probar que lo haga mediante OAuth 2.0 Playground. Después, puedes comparar los encabezados HTTP y enviar una solicitud a Playground para saber qué transfiere tu aplicación a Google Analytics. Esta comprobación es una forma sencilla de comprobar que aplicas el formato correcto a tus solicitudes.

Concesión no válida

Cuando intentas utilizar un token de actualización, obtienes un error invalid_grant en los casos siguientes:

  • El reloj de tu servidor no está sincronizado con el protocolo NTP.
  • Se ha superado el límite de tokens de actualización.

Las aplicaciones pueden solicitar varios tokens de actualización para acceder a una sola cuenta de Google Analytics.

Por ejemplo, si un usuario quiere instalar una aplicación en varios ordenadores y acceder a la misma cuenta de Google Analytics, necesitará un token distinto para cada ordenador. 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. Si la aplicación sigue solicitando tokens de actualización para el mismo par de cliente y cuenta, cuando se solicita el token número 26, el primer token de actualización que se emitió deja de ser válido. El token de actualización número 27 que se solicite invalidará el segundo token emitido, y así sucesivamente.