Aprovisionamiento de cuentas controladas por el usuario: Guía para desarrolladores de la API

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

Introducción

La API de Provisioning se puede usar para crear cuentas nuevas de Google Analytics y habilitar Google Analytics para tus clientes a gran escala. Está destinada a proveedores de servicios calificados y grandes socios. Visita la Descripción general de la API de Provisioning para obtener una introducción a la API de Provisioning.

Antes de comenzar

Se accede a todas las APIs de Google Analytics de manera similar. Antes de comenzar a usar la API de aprovisionamiento, debes hacer lo siguiente:

  • Lee la página de 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 obtener más información sobre la interfaz de la API y cómo acceder a los datos sin una biblioteca cliente.

Cada biblioteca cliente proporciona un único objeto de servicio de estadísticas para acceder a la API de Provisioning. Por lo general, debes seguir estos pasos para crear el objeto de servicio:

  1. Registra tu aplicación en la Consola de API de Google.
  2. Autorice la creación de una cuenta nueva de Google Analytics.
  3. Crear un objeto de servicio de Analytics

Si no completaste estos pasos, detente y lee el instructivo Hello Google Analytics API Tutorial. En este instructivo, se indican los pasos iniciales para crear una aplicación de la API de Google Analytics. Cuando termines, comprenderás cómo acceder a las APIs de Google Analytics para realizar tareas reales.

Descripción general

Cuando creas cuentas de Google Analytics con la API de Provisioning, hay 2 flujos independientes que debes considerar:

  • Flujo técnico: Es el flujo de extremo a extremo que permite aprovisionar de manera programática una cuenta de Google Analytics para un usuario.
  • Flujo de usuarios: Son las consideraciones de implementación que debes tener en cuenta para el flujo de creación de la cuenta desde la perspectiva del usuario.

En este documento, se describen los pasos y requisitos de alto nivel para cada flujo.

Flujo técnico

Los pasos de alto nivel para usar la API de Provisioning para crear una cuenta nueva y, luego, integrarla en Google Analytics son los siguientes:

  1. Solicita al usuario que autentica y autorice la aplicación o el servicio con OAuth 2.0.
  2. Crea un ticket de cuenta con la API de Provisioning.
  3. Redirecciona al usuario para que acepte las Condiciones del Servicio de Google Analytics y maneje la respuesta.
  4. Opcional: Configura la cuenta y las oportunidades de integración.

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

Cada uno de los siguientes pasos tiene los Requisitos para completar el paso, los Resultados y una descripción del Flujo técnico del paso.

1. Autenticación y autorización

Cada usuario debe autorizar tu aplicación y otorgarle la capacidad de aprovisionar una cuenta de Google Analytics en su nombre. Se sugiere el flujo de la aplicación del servidor web de OAuth 2.0 para completar este paso.

Qué necesitas para completar este paso

El resultado de este paso

Una vez que se complete el flujo de OAuth 2.0, el usuario habrá autorizado tu aplicación para aprovisionar una cuenta en su nombre y tú tendrás un Token de acceso para el usuario.

Nota sobre los tokens y permisos:

  • Si quieres realizar solicitudes adicionales para la configuración de la cuenta del usuario o los datos de informes después de crearla, puedes autorizar permisos adicionales durante este paso. Por ejemplo, los permisos readonly o edit.
  • Los tokens de acceso tienen una vida útil limitada. Si tu aplicación necesita acceder a la API de Google Analytics más allá de la vida útil de un solo token de acceso, también puedes solicitar un token de actualización configurando el access_type=offline. Se debe guardar un token de actualización en un almacenamiento seguro a largo plazo para cada usuario, ya que le permite a tu aplicación obtener nuevos tokens de acceso. Consulta Acceso sin conexión para obtener detalles adicionales.

El flujo técnico para este paso

Debes obtener un token de acceso para el usuario. Según el flujo descrito en el servidor web de OAuth 2.0, envía al usuario al servicio de Cuentas de Google y controla la respuesta cuando se vuelva a redireccionar a tu servicio después de completar el flujo de autenticación.

Crear la URL de OAuth 2.0 para que visite el usuario

Cuando el usuario hace clic en un botón o vínculo para Comenzar o Crear una cuenta, el vínculo debe dirigir al inicio del flujo de OAuth 2.0 para solicitarle al usuario que otorgue permisos de aprovisionamiento. 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}
Controla la respuesta del servicio de Cuentas de Google

Una vez que el usuario tome la decisión de otorgar acceso a la aplicación, se lo redireccionará a redirect_uri, como se especifica en la URL que formó con un parámetro de consulta que contiene un código de autorización. Si el usuario aprobó la solicitud, se puede usar la respuesta del código de autorización para intercambiar el código de autorización por un token de acceso mediante una solicitud POST a la API de Cuentas de Google.

Guarda el token de actualización (si corresponde)

En el siguiente paso, se usará el token de acceso para que puedas almacenarlo temporalmente. Si también solicitaste un token de actualización para el usuario, debes almacenarlo de forma segura para un uso a largo plazo. Un token de actualización es de larga duración y se puede usar para emitir tokens de acceso nuevos.

2. Crea un ticket de cuenta con la API de Provisioning

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

Qué necesitas para completar este paso

Un token de acceso para el usuario autorizado, como se describe en Autenticación y autorización, y en los siguientes detalles de aprovisionamiento:

  • URI de redireccionamiento
    • Define a dónde se redirecciona al usuario después de la página Condiciones del Servicio de Google Analytics. Puede ser diferente 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, la mayúscula y la “/” final).
  • Campos de la cuenta
    • La cuenta obligatorio tiene una propiedad name.
  • Campos de propiedad web
    • La propiedad name es obligatoria para ella.
    • Es obligatorio un websiteUrl.
  • Campos del perfil
    • Una propiedad name es obligatoria para el perfil.
    • De manera opcional, se puede proporcionar un timezone. El valor predeterminado es America/Los_Angeles.

Cuando se crea un ticket de cuenta, solo se pueden configurar los campos básicos identificados anteriormente. Una vez creada la cuenta, se pueden realizar cambios de configuración adicionales en la propiedad o vista (perfil) mediante la API de Management.

Si deseas obtener detalles adicionales sobre estos campos, consulta la referencia de la API para cuentas, propiedades y vistas (perfiles).

El resultado de este paso

Una vez que se realiza una solicitud correcta a la API de Provisioning, tendrás un ticket de cuenta de corta duración para el usuario. El ID del ticket de cuenta se usa en el paso final para solicitarle al usuario que acepte las Condiciones del Servicio y active su cuenta. La cuenta no puede usarse hasta que las aceptes.

El flujo técnico para este paso

Con el token de acceso del usuario que se obtuvo durante la autenticación y autorización, se realiza una solicitud HTTP POST a la API de Provisioning.

Solicitud a la API de Provisioning para crear el ticket de cuenta

Revisa el método createAccountTicket en la referencia de la API de Provisioning para obtener detalles sobre cómo realizar la solicitud.

Respuesta de la API de Provisioning

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

Consulta Account Ticket resource en la referencia de la API de administración para obtener detalles sobre la respuesta.

La aplicación también debe controlar las respuestas de error.

3. El usuario acepta las Condiciones del Servicio de Google Analytics

Después de tener un ID del ticket de cuenta para el usuario, puedes usarlo con la solicitud de las Condiciones del Servicio para solicitarle al usuario que acepte las Condiciones del Servicio de Google Analytics.

Qué necesitas para completar este paso

Un ID de ticket de cuenta para el usuario autorizado

El resultado de este paso

Después de completar correctamente el flujo de las Condiciones del Servicio con el ID del ticket de cuenta, se crearán la cuenta, la propiedad y la vista (perfil). El usuario ahora tendrá una cuenta activa. La respuesta de la página de las Condiciones del Servicio incluirá el ID de la cuenta, el ID de propiedad y el ID de la vista (perfil).

El flujo técnico para este paso

Con el ID del ticket de cuenta, redirecciona al usuario a la página de las Condiciones del Servicio de Google Analytics, donde puede aceptar las Condiciones del Servicio; luego, deberás manejar la respuesta de la API.

Crea la URL de las Condiciones del Servicio que debe visitar el usuario.

Redirecciona al usuario a la página de las Condiciones del Servicio y, luego, incluye el ID del ticket de cuenta como parte de la URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Controla la respuesta de las Condiciones del Servicio

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

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

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

Por ejemplo, si el controlador de las Condiciones del Servicio de tu aplicación se encuentra en http://www.your-app.com/gaTOS, se debe configurar como redirectUri cuando crees tickets de cuenta. El controlador de las Condiciones del Servicio de la aplicación debe esperar y manejar adecuadamente las solicitudes HTTP GET que contengan parámetros de consulta accountId, webPropertyId, profileId y accountTicketId para los casos en los que el ticket de la cuenta es válido y el usuario aceptó las Condiciones del Servicio.

Las respuestas sin éxito incluirán la respuesta del error:

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

El controlador de las Condiciones del Servicio también debe controlar de forma adecuada las solicitudes HTTP GET que contienen un parámetro de consulta error, lo que indica que se produjo un error. El valor del parámetro de búsqueda se puede usar para realizar más acciones o mostrar un mensaje al usuario:

  • error=user_cancel: El usuario no aceptó las Condiciones del Servicio.
  • error=max_accounts_reached: El usuario alcanzó el límite de cuentas de Google Analytics.
  • error=backend_error: es un error general. El servidor mostró un error que no está en las categorías anteriores.

4. Oportunidades de integración (opcional)

Si seguiste el flujo técnico anterior, entonces habrás creado una cuenta para el usuario y tendrás el ID de la cuenta, el ID de propiedad y el ID de la vista (perfil). Si también solicitaste permisos adicionales, es posible que tengas un token de actualización para el usuario. Con estos datos, puedes hacer lo siguiente:

Flujo de usuarios

En esta sección, se describen las consideraciones de implementación relacionadas con los pasos del flujo de creación de la cuenta desde la perspectiva del usuario.

El flujo comienza cuando el usuario ofrece las siguientes 2 opciones para habilitar las estadísticas en su propiedad:

  1. Crea una cuenta de Google Analytics
  2. Usa una cuenta de Google Analytics existente. (Nota: Este flujo no se trata en este documento. Consulta la API de Management para obtener detalles sobre cómo acceder a los datos de configuración de Google Analytics de un usuario).

Cuando creas una cuenta nueva de Google Analytics, hay información que debes enviar junto con la solicitud de aprovisionamiento, 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 que desees mostrarles, hay 3 opciones principales para iniciar el flujo de usuarios después de que el usuario haga clic en “crear cuenta”:

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

En este caso, se le solicitan los detalles de la cuenta al usuario en medio del proceso. El flujo será similar al siguiente:

  1. Se redirecciona al usuario al servicio de la Cuenta de Google para el flujo de OAuth 2.0. Si el usuario no tiene una Cuenta de Google o no accedió a una, se le pedirá que cree una Cuenta de Google o que acceda a una cuenta.
  2. Se le solicita al usuario que autorice la aplicación para "Crear cuentas de Google Analytics".
  3. El usuario acepta solicitudes de permisos para la aplicación.
  4. Se redirecciona al usuario al proveedor de servicios. Ten en cuenta que, si el usuario rechaza la autorización, se lo redireccionará nuevamente al proveedor de servicios.
  5. Se presenta un formulario al usuario para recopilar detalles sobre la cuenta que creará (p.ej., nombre de la cuenta, nombre de la propiedad, nombre del perfil, zona horaria, URL del sitio web, etcétera).
  6. El usuario completa y envía el formulario, y se lo redirecciona a Google, o se le muestran las Condiciones del Servicio de Google Analytics.
  7. El usuario acepta las Condiciones del Servicio.
  8. Se redirecciona al usuario al proveedor de servicios, y se le muestra un mensaje de éxito en el que se indica que creó una cuenta de Google Analytics de forma correcta con los detalles de la cuenta y cómo acceder a ella. Ten en cuenta que, si el usuario no acepta las Condiciones del Servicio, se lo redireccionará nuevamente al proveedor de servicios.

Solicita detalles de la cuenta antes de la autorización

En este caso, se le solicita al usuario por adelantado los detalles de configuración de la cuenta que se creará. El flujo será similar al siguiente:

  1. En el sitio del Proveedor de servicios, se presenta un formulario al usuario para recopilar detalles sobre la cuenta que debe crear (p.ej., nombre de la cuenta, de la propiedad, del perfil, de la zona horaria y URL del sitio web).
  2. El usuario completa el formulario, hace clic en Enviar y se lo redirecciona al servicio de Cuentas de Google para el flujo de OAuth 2.0. Si el usuario no tiene una Cuenta de Google o no accedió a una, se le pedirá que cree una Cuenta de Google o que acceda a una cuenta.
  3. Se le solicita al usuario que autorice la aplicación para "Crear cuentas de Google Analytics".
  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 de Google Analytics.
  7. El usuario acepta las Condiciones del Servicio.
  8. Se redirecciona al usuario al proveedor de servicios, y se le muestra un mensaje de éxito en el que se indica que creó una cuenta de Google Analytics de forma correcta con los detalles de la cuenta y cómo acceder a ella.

Precompletar detalles de la cuenta u omitir formularios

Si ya hay información disponible sobre la cuenta de usuario (p.ej., URL del sitio web, nombre del sitio web, zona horaria, etc.), puedes simplificar aún más las dos opciones anteriores:

  • Completar previamente el formulario y permitir que el usuario lo edite si lo desea.
  • Se omite por completo el paso del formulario y se crea automáticamente la cuenta con la información existente.