API de gestión de cuentas: guía para desarrolladores

En este documento se explican conceptos importantes sobre el uso de la API de gestión de cuentas para crear nuevas cuentas de Google Analytics.

Introducción

La API de gestión de cuentas se puede usar para crear nuevas cuentas de Google Analytics y habilitar Google Analytics para los clientes según la escala que necesites. Se ha diseñado para los proveedores de servicio y partners grandes que cumplan los requisitos. Si es la primera vez que usas la API, consulta Descripción general de la API de gestión de cuentas para obtener una introducción a dicha API.

Antes de empezar

A todas las API de Google Analytics se accede de un modo similar. Antes de empezar a usar la API de gestión de cuentas, debes realizar las siguientes acciones:

  • Consulta la página de bibliotecas de cliente para obtener una lista completa de las bibliotecas de cliente específicas del lenguaje de programación que funcionan con la API.
  • Consulta la guía de referencia para obtener información sobre la interfaz de la API y el acceso a los datos sin una biblioteca de cliente.

Cada biblioteca de cliente proporciona un solo objeto de servicio analytics para acceder a la API de gestión de cuentas. Por lo general, para crear el objeto de servicio tienes que realizar los pasos siguientes:

  1. Registrar tu aplicación en la consola de la API de Google
  2. Autorizar la creación de una nueva cuenta de Google Analytics
  3. Crear un objeto de servicio Analytics.

Si no has completado estos pasos, no sigas y lee el tutorial de presentación de la API de Google Analytics. Con este tutorial recorrerás los pasos iniciales de la creación de una aplicación de la API de Google Analytics. Una vez completado, sabrás cómo acceder a las API de Google Analytics para realizar tareas del mundo real.

Descripción general

Al crear cuentas de Google Analytics mediante la API de gestión de cuentas, hay dos flujos independientes que se deben tener en cuenta:

  • Flujo técnico: flujo completo para crear programáticamente una cuenta de Google Analytics a un usuario.
  • Flujo de usuario: consideraciones de implementación que debes plantearte en el flujo de creación de la cuenta desde el punto de vista del usuario.

En este documento se describen los pasos generales y los requisitos de cada flujo.

Flujo técnico

Los pasos generales para usar la API de gestión de cuentas para crear una nueva cuenta e integrarla con Google Analytics son:

  1. Pedir al usuario que autentique y autorice la aplicación o el servicio con OAuth 2.0.
  2. Crear un ticket de cuenta con la API de gestión de cuentas.
  3. Redireccionar al usuario para que acepte las Condiciones del servicio (TOS) de Google Analytics y gestionar la respuesta.
  4. (Opcional) Configurar la cuenta y las oportunidades de integración.

Si todos estos pasos se realizan correctamente, se crea una cuenta de Google Analytics para el usuario y tendrás el ID de cuenta, el ID de propiedad y el ID de vista (perfil) de la nueva cuenta.

Para cada uno de estos pasos hay requisitos para completar el paso, resultados del paso y una descripción del flujo técnico del paso.

1. Autenticación y autorización

Cada usuario debe autorizar tu aplicación y concederle la posibilidad de crear una cuenta de Google Analytics en su nombre. Se recomienda el flujo de aplicación del servidor web de OAuth 2.0 para realizar este paso.

Qué se necesita para completar este paso

Resultado de este paso

Una vez que se haya completado el flujo de OAuth 2.0, el usuario habrá autorizado tu aplicación para crear una cuenta en su nombre y tendrás un token de acceso para el usuario.

Nota sobre los tokens y los ámbitos:

  • Si tienes previsto hacer solicitudes adicionales de los datos de configuración o de informe de la cuenta del usuario después de que esta se haya creado, podrías autorizar ámbitos adicionales durante este paso. Por ejemplo, los ámbitos readonly o edit.
  • Los tokens de acceso tienen una duración limitada. Si tu aplicación necesita acceder a la API de Google Analytics después del ciclo de vida de un token de acceso individual, también puedes solicitar un token de actualización configurando access_type=offline. Los tokens de actualización se deben guardar en un almacenamiento duradero y seguro por cada usuario ya que permite que tu aplicación obtenga nuevos tokens de acceso. Si deseas obtener más información al respecto, consulta Acceso offline.

Flujo técnico de este paso

Debes obtener un token de acceso para un usuario. Según el flujo descrito en Servidor web de OAuth 2.0, envía al usuario al servicio de cuentas de Google Analytics y, a continuación, gestiona la respuesta cuando se le vuelva a redireccionar a tu servicio una vez completado el flujo de autorización.

Crear la URL de OAuth 2.0 que visitará el usuario

Cuando el usuario hace clic en un botón o en un enlace para empezar o crear una cuenta, el enlace debe apuntar al inicio del flujo de OAuth 2.0 para que le pida al usuario que conceda los permisos de creación de cuentas. Por ejemplo:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Gestionar la respuesta del servicio de cuentas de Google

Una vez que el usuario tome la decisión de conceder acceso a tu aplicación, se le redireccionará a redirect_uri, según lo especificado en la URL que has creado con un parámetro de consulta que contiene un código de autorización. Si el usuario ha aprobado la solicitud, la respuesta del código de autorización se puede usar para intercambiar el código de autorización de un token de acceso realizando una solicitud POST a la API de cuentas de Google.

Guardar el token de acceso (si corresponde)

El token de acceso se usará en el paso siguiente para que puedas guardarlo temporalmente. Si también has solicitado un token de actualización para el usuario, también debes almacenarlo de forma segura para un uso a largo plazo. El token de actualización tiene un ciclo de vida largo y se puede usar para emitir nuevos tokens de acceso.

2. Crear un ticket de cuenta con la API de gestión de cuentas

Una vez que tengas un token de acceso para el usuario autorizado, puedes usarlo para realizar una solicitud a la API de gestión de cuentas con el fin de crear un ticket de cuenta para el usuario. El ticket de cuenta es el primer paso para crear una cuenta para un usuario.

Qué se necesita para completar este paso

Un token de acceso para el usuario autorizado, según se describe en Autenticación y autorización, y la siguiente información de creación de cuentas:

  • URI de redireccionamiento
    • Define a dónde se redirecciona al usuario después de la página de las Condiciones del servicio (TOS) de Google Analytics. Puede ser distinto del URI de redireccionamiento especificado durante el flujo de autorización de OAuth 2.0.
    • El valor del parámetro de URI de redireccionamiento debe coincidir exactamente con uno de los valores registrados en Google Developers Console (incluidos los esquemas http o https, las mayúsculas y minúsculas, y el signo "/" al final).
  • Campos de cuenta
    • Se debe indicar una propiedad name para la cuenta.
  • Campos de la propiedad web
    • Se debe indicar una propiedad name para la propiedad.
    • Se debe especificar websiteUrl.
  • Campos del perfil
    • Se debe indicar una propiedad name para el perfil.
    • Si se desea, se puede indicar un valor para timezone. El valor predeterminado es America/Los_Angeles.

Al crear un ticket de cuenta, solo se pueden configurar los campos básicos identificados más arriba. Una vez que se ha creado la cuenta, los cambios de configuración adicionales en la propiedad o en la vista (perfil) se pueden realizar con la API de administración.

Consulta la referencia de la API de cuentas, propiedades y vistas (perfiles) para obtener información adicional sobre estos campos.

Resultado de este paso

Después de que se realice una solicitud correcta a la API de gestión de cuentas, tendrás un ticket de cuenta de corta duración para el usuario. El ID de ticket de cuenta se utiliza en el paso final para pedir al usuario que acepte las Condiciones del servicio (TOS) y active su cuenta. La cuenta no se podrá usar hasta que no se acepten las TOS.

Flujo técnico de este paso

Con el token de acceso correspondiente al usuario que se ha obtenido durante el proceso de autenticación y autorización, se ha realizado una solicitud HTTP POST a la API de gestión de cuentas.

Solicitud a la API de gestión de cuentas para crear el ticket de cuenta

Consulta el método createAccountTicket en la API de gestión de cuentas para obtener información detallada sobre cómo realizar la solicitud.

Respuesta de la API de gestión de cuentas

Una solicitud correcta devuelve una respuesta 200. El cuerpo de la respuesta contiene un ticket de cuenta, que es de corta duración. Este ticket consta de un ID y de los detalles del nuevo árbol de la cuenta.

Consulta el Account Ticket resource en la referencia de la API de gestión de cuentas para obtener información detallada sobre la respuesta.

La aplicación también tiene que gestionar las respuestas de error.

3. El usuario acepta las Condiciones del servicio (TOS) de Google Analytics

Una vez que tengas un ID de ticket de cuenta para el usuario, puedes usarlo con la solicitud de las TOS para pedir al usuario que acepte las Condiciones del Servicio de Google Analytics.

Qué se necesita para completar este paso

Un ID de ticket de cuenta para el usuario autorizado.

Resultado de este paso

Después de completar correctamente el flujo de las TOS usando el ID de ticket de cuenta, se creará la cuenta, la propiedad y la vista (perfil). Desde ese momento, el usuario tendrá una cuenta activa. La respuesta de la página de las TOS incluirá el ID de cuenta, el ID de propiedad y el ID de vista (perfil).

Flujo técnico de este paso

Usando el ID de ticket de usuario, redirecciona al usuario a la página de las TOS de Google Analytics, donde puede aceptarlas. Después, debes gestionar la respuesta de la API.

Crear la URL de TOS que visitará el usuario

Redirecciona al usuario a la página de las TOS e incluye el ID de ticket de cuenta como parte de la URL:

https://www.google.com/analytics/web/?provisioningSignup=false#management/TermsOfService//?
  api.accountTicketId={account_ticket_id}
Gestionar la respuesta de las TOS

Después de que el usuario realice alguna acción en la página de las TOS, se le redireccionará al redirectUri especificado durante la creación del ticket de cuenta. La respuesta de la página de las TOS se incluirá como parte de la cadena de consulta.

Las respuestas correctas devolverán datos sobre la estructura de cuenta recién creada, así como el accountTicketId original:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Por ejemplo, si el controlador de las TOS de tu aplicación está en http://www.your-app.com/gaTOS, se debe configurar como redirectUri al crear tickets de cuenta. El controlador de las TOS de tu aplicación debe esperar y gestionar correctamente las solicitudes HTTP GET que contengan los parámetros de consulta accountId, webPropertyId, profileId y accountTicketId en los casos en que el ticket de cuenta sea válido y el usuario haya aceptado las TOS.

Las respuestas incorrectas devolverán la respuesta de error:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

El controlador de las TOS también debe gestionar correctamente las solicitudes HTTP GET que contengan un parámetro de consulta error, lo que indica que se ha producido un error. El valor del parámetro de consulta se puede usar para realizar alguna acción o mostrar un mensaje al usuario:

  • error=user_cancel: el usuario no ha aceptado las condiciones del servicio.
  • error=max_accounts_reached: el usuario ha alcanzado el límite de cuentas de Google Analytics.
  • error=backend_error: error general. El servidor ha devuelto un error que no se encuentra en las categorías anteriores.

4. (Opcional) Oportunidades de integración

Si has seguido el flujo técnico anterior, habrás creado una cuenta para el usuario y tendrás el ID de cuenta, el ID de propiedad y el ID de vista (perfil). Asimismo, si has solicitado permisos adicionales, también tendrás un token de actualización para el usuario. Con estos datos puedes:

Flujo del usuario

En esa sección se describen las consideraciones de implementación relacionadas con los pasos del flujo de creación de cuenta desde el punto de vista del usuario.

El flujo empieza ofreciendo al usuario las dos opciones siguientes para habilitar Analytics en su propiedad:

  1. Crear una cuenta de Google Analytics.
  2. Usar una cuenta de Google Analytics existente. Nota: Este flujo no se describe en este documento. Consulta la API de administración para obtener información detallada sobre cómo acceder a los datos de configuración de Google Analytics de un usuario.

Al crear una nueva cuenta de Google Analytics hay información que debes enviar con la solicitud de creación de cuentas, como el nombre de la cuenta, el nombre de la propiedad, etc. Según la información que tengas sobre el usuario y el flujo preferido, puedes mostrarle tres opciones principales para iniciar el flujo de usuario después de que este haga clic en "Crear cuenta":

Solicitar los datos de la cuenta después de la autorización

En este caso se le pide al usuario la información de la cuenta en medio del proceso. El flujo debe ser similar al siguiente:

  1. Se redirecciona al usuario al servicio de cuentas de Google para realizar el flujo de OAuth 2.0. Si el usuario no tiene una cuenta de Google o no ha iniciado sesión, se le pedirá que cree una cuenta de Google o que inicie sesión.
  2. Al usuario se le pide que conceda el permiso "Crear cuentas de Google Analytics" a la aplicación.
  3. El usuario acepta la solicitud de permiso de la aplicación.
  4. Se redirecciona al usuario al proveedor de servicios. Si el usuario rechaza la autorización, se le redireccionará igualmente al proveedor de servicios.
  5. Se presentará un formulario al usuario para recopilar información sobre la cuenta que se creará (por ejemplo, nombre de la cuenta, nombre de la propiedad, nombre del perfil, zona horaria, URL del sitio web, etc.).
  6. El usuario completa y envía el formulario y se le redirecciona a Google o se le muestran las Condiciones del servicio (TOS) de Google Analytics.
  7. El usuario acepta las TOS.
  8. Se redirecciona al usuario al proveedor de servicios y se le muestra un mensaje en el que se indica que ha creado una cuenta de Google Analytics con información sobre la cuenta y cómo acceder a ella. Si el usuario no acepta las TOS, se le redireccionará igualmente al proveedor de servicios.

Solicitar los datos de la cuenta antes de la autorización

En este caso, al usuario se le pide por adelantado la información de configuración de la cuenta que se va a crear. El flujo debe ser similar al siguiente:

  1. En el sitio del proveedor de servicio, se presentará un formulario al usuario para recopilar información sobre la cuenta que se creará (por ejemplo, nombre de la cuenta, nombre de la propiedad, nombre del perfil, zona horaria, URL del sitio web, etc.).
  2. El usuario completa el formulario y se le redirecciona al servicio de cuentas de Google para realizar el flujo de OAuth 2.0. Si el usuario no tiene una cuenta de Google o no ha iniciado sesión, se le pedirá que cree una cuenta de Google o que inicie sesión.
  3. Al usuario se le pide que conceda el permiso "Crear cuentas de Google Analytics" a la aplicación.
  4. El usuario acepta los permisos solicitados para la aplicación.
  5. Se redirecciona al usuario al proveedor de servicios.
  6. Se redirecciona al usuario a Google o se le muestran las Condiciones del servicio (TOS) de Google Analytics.
  7. El usuario acepta las TOS.
  8. Se redirecciona al usuario al proveedor de servicios y se le muestra un mensaje en el que se indica que ha creado una cuenta de Google Analytics con información sobre la cuenta y cómo acceder a ella.

Completar previamente los datos de la cuenta o saltarse formularios

Si la información sobre la cuenta del usuario está disponible (por ejemplo, URL del sitio web, nombre del sitio web, zona horaria, etc.), se pueden simplificar ambas opciones de la siguiente forma:

  • Completar previamente el formulario y permitir al usuario que lo modifique si así lo desea.
  • Saltarse totalmente el paso del formulario y crear automáticamente la cuenta a partir de la información existente.