Configura Google Cloud y OAuth

El acceso a la API de Google Health se proporciona a través de Google Cloud. Para habilitar la API y autorizar una Cuenta de Google, necesitarás un proyecto de Google Cloud.

Ya sea que seas un desarrollador de la API de Fitbit o que recién comiences a usar la API de Google Health, deberás completar este paso para realizar llamadas a la API.

Crea un proyecto y un cliente de OAuth

Usa el botón Habilita la API y obtén un ID de cliente de OAuth 2.0 para habilitar la API de Google Health y obtener un ID de cliente de OAuth 2.0:

  1. Si tienes un proyecto de Google Cloud existente que te gustaría usar para la API de Google Health, asegúrate de acceder primero a la cuenta de administrador de ese proyecto. Luego, selecciona el proyecto existente de la lista de proyectos disponibles después de hacer clic en el botón. De lo contrario, crea un proyecto nuevo.
  2. Selecciona Servidor web cuando se te pregunte "¿Desde dónde llamas?".
  3. Ingresa https://www.google.com como el valor de URIs de redireccionamiento autorizados. Se requiere un URI de redireccionamiento para obtener un código de autorización con OAuth 2.0.
  4. Una vez que se complete la configuración, copia los valores del ID de cliente y el secreto del cliente de OAuth 2.0, y descarga el archivo JSON de credenciales en tu máquina local.
Habilita la API y obtén un ID de cliente de OAuth 2.0

Si quieres configurar manualmente tu proyecto de Google Cloud o verificar la configuración y recuperar tus credenciales de nuevo, sigue estos pasos:

  1. Habilita la API de Google Health en la página Habilitación de la API.
  2. Obtén un ID de cliente de OAuth 2.0 en la página Credenciales.

Para obtener más información sobre cómo configurar OAuth 2.0 con la consola de Google, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Usa proyectos independientes para la etapa de pruebas y la producción

La API de Google Health no proporciona un entorno de pruebas o de etapa de pruebas independiente. Todos tus entornos llaman a la API de Google Health de producción, por lo que administras la separación de entornos a nivel del proyecto de Google Cloud.

Cuando configures entornos para tu app, sigue estas prácticas recomendadas:

  • Crea proyectos de Google Cloud independientes para tus entornos de desarrollo, etapa de pruebas y producción. Cada proyecto administra su propio cliente de OAuth 2.0, pantalla de consentimiento y suscriptores de webhook.
  • No uses tu proyecto de Google Cloud de producción ni su cliente de OAuth 2.0 para realizar pruebas, ya que los cambios en ese proyecto afectan directamente a tu app de producción.
  • Primero, desarrolla y prueba en un proyecto que no sea de producción y, luego, aplica los cambios al proyecto de producción cuando esté listo.
  • Usa etiquetas en la consola de Google Cloud para distinguir visualmente tus proyectos por entorno. Para obtener instrucciones, consulta Designa entornos de proyectos con etiquetas.

Agrega usuarios de prueba

De forma predeterminada, los clientes de OAuth recién creados se encuentran en un estado no verificado con un límite de 100 usuarios para fines de prueba y producción. Para habilitar la autorización durante este período, debes agregar manualmente la dirección de correo electrónico de cada usuario a la lista de usuarios de prueba en la configuración del proyecto.

Actualiza la lista de usuarios de prueba en la página Público:

  1. En esta página, deberías ver el "Estado de publicación" establecido en Prueba y el "Tipo de usuario" establecido en Externo.
  2. En la sección "Usuarios de prueba", haz clic en + Agregar usuarios. Ingresa la dirección de correo electrónico de los usuarios de prueba que deberían poder otorgar permiso a tu app para acceder a sus datos de salud.
  3. Haz clic en Guardar.

Para admitir a más de 100 usuarios con la API de Google Health, se debe completar una revisión de seguridad de terceros. Puedes encontrar más información en el Centro de ayuda de verificación de apps de OAuth.

Supervisa los límites de frecuencia de otorgamiento de tokens de OAuth

Google Cloud aplica un límite de frecuencia en el otorgamiento de tokens de OAuth para controlar la rapidez con la que tu app puede incorporar o volver a autenticar a los usuarios. Si prevés que superarás los 10,000 registros o reautenticaciones de usuarios en un período de 24 horas, solicita una cuota más alta con anticipación. Para obtener más información, consulta Límites de frecuencia de la aplicación de OAuth.

Agrega permisos

Debes especificar los permisos que tu cliente puede llamar en la página Acceso a los datos:

  1. En esta página, haz clic en Agregar o quitar permisos.
  2. En la columna API, busca "API de Google Health". Selecciona los permisos que necesitas para tu aplicación.
  3. Después de seleccionar todos los permisos que necesitas, haz clic en Actualizar para volver a la página Acceso a los datos.
  4. Haz clic en Guardar.

Antes de seleccionar tus permisos, revisa la implementación de permisos.

Terminaste de configurar tu ID de cliente y ahora deberías poder realizar llamadas a la API de Google Health.

Actualiza los permisos

Puedes pedirle al usuario que vuelva a autorizar tu app configurando el parámetro prompt como consent en tu solicitud de autenticación. Cuando se incluye prompt=consent, la pantalla de consentimiento se muestra cada vez que tu app solicita la autorización de los permisos de acceso, incluso si todos los permisos se otorgaron anteriormente a tu proyecto de las APIs de Google.

Para agregar o cambiar permisos con el parámetro prompt=consent, sigue estos pasos:

  1. Identifica la lista completa de permisos que necesita tu aplicación. Esto debe incluir los permisos existentes y los nuevos que necesites agregar.

  2. Modifica el parámetro de alcance en la URL de autorización para incluir la lista actualizada de valores de alcance separados por espacios.

  3. Agrega prompt=consent a los parámetros de URI de autenticación. Esto obliga al servidor de autorización a solicitar el consentimiento del usuario antes de devolver información a tu cliente.

    En el siguiente ejemplo, se muestra una solicitud GET de HTTPS al extremo de autorización de OAuth 2.0 de Google que solicita varios permisos con prompt=consent adjunto:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Cuando el usuario siga el vínculo actualizado, se le presentará una página de consentimiento en la que se enumerarán todos los permisos solicitados. Una vez que el usuario haga clic en "Continuar" o "Permitir", recibirás un nuevo código de autorización que se puede intercambiar por tokens que cubran el conjunto completo de permisos.

    Incluye prompt=consent solo cuando sea necesario, como cuando necesites obtener un token de actualización nuevo o cuando hayan cambiado los permisos solicitados.

Bibliotecas cliente de OAuth2

La lista de bibliotecas cliente de OAuth2 disponibles que se usan para la integración en frameworks populares se puede encontrar en Usa OAuth 2.0 para acceder a las APIs de Google.

Cuando implementes Google OAuth en apps para dispositivos móviles o computadoras, usa siempre navegadores del sistema (como las pestañas personalizadas de Chrome en Android o ASWebAuthenticationSession en iOS) y nunca uses WebViews incorporadas, que bloquean las llaves de acceso y rompen los flujos de Google OAuth. Revisa las prácticas recomendadas de Acceder con Google para obtener orientación.

Antes de que un usuario pase por el flujo de consentimiento de Google OAuth 2.0 en tu app, debe acceder a la app para dispositivos móviles de Google Health para vincular Google Health con su Cuenta de Google. Google OAuth 2.0 autentica cualquier Cuenta de Google válida y no puede verificar si la cuenta tiene un perfil de Google Health activo durante la pantalla de consentimiento.

Indica a los usuarios que completen los siguientes pasos en la app para dispositivos móviles de Google Health antes de iniciar el flujo de consentimiento de OAuth en tu app:

  1. Descarga y abre la app para dispositivos móviles de Google Health desde Google Play Store o App Store de Apple.
  2. Presionar Acceder con Google y seleccionar la Cuenta de Google que quieren conectar a tu app
  3. Sigue las indicaciones de la app para crear un nuevo perfil de Google Health o sigue los pasos de migración de la cuenta de Fitbit para transferir una cuenta de Fitbit existente a su Cuenta de Google.

Después de intercambiar el código de autorización por tokens de OAuth, llama al extremo users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) para verificar que la Cuenta de Google del usuario esté vinculada a Google Health antes de marcar la cuenta como conectada en tu app. Para obtener detalles sobre cómo controlar las cuentas no vinculadas (400 ACCOUNT_NOT_LINKED), consulta Cómo controlar las Cuentas de Google no vinculadas.

Tokens de actualización

Para mantener el acceso a largo plazo a las APIs de Google sin requerir una reautenticación constante del usuario, tu aplicación debe usar un token de actualización. Para obtener detalles completos de la implementación, incluidas las solicitudes HTTP y los parámetros específicos necesarios, consulta la documentación de la plataforma de identidad de Google.

Para intercambiar un token de actualización por un token de acceso, realiza una llamada HTTPS POST al endpoint del Google OAuth 2.0. En el siguiente fragmento, se muestra un ejemplo de solicitud y respuesta:

Solicitud

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Respuesta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token_expires_in": 112154
}

Cuándo actualizar un token

Actualiza los tokens según demanda como parte de la progresión natural de la sesión activa de un usuario cuando los tokens de acceso hayan vencido o estén por vencer. Evita actualizar los tokens de actualización en lotes (por ejemplo, con un trabajo o servicio de cron programado para actualizar los tokens de todos los usuarios en un momento fijo).

No se recomienda actualizar los tokens de actualización por lotes por los siguientes motivos:

  • La actualización por lotes evita que las actualizaciones de tokens se alineen con los patrones de sincronización de usuarios activos. Si bien puedes usar la llamada Get Devices para ver la hora de la última sincronización de un usuario, esto requiere un permiso de OAuth adicional que los usuarios no están obligados a aprobar.
  • El procesamiento por lotes actualiza los tokens que no necesitan actualizarse, lo que genera una sobrecarga de procesamiento redundante tanto para tus sistemas como para los servidores de Google.
  • Si se produce un problema de red o una interrupción del servidor durante una actualización por lotes, todos los tokens de usuario afectados se verán afectados a la vez. Actualizar los tokens de actualización de forma individual durante la progresión natural de las sincronizaciones de usuarios aísla el impacto de las fallas transitorias a un solo usuario.
  • Diagnosticar problemas es más difícil con los trabajos por lotes. Debido a que las solicitudes por lotes se producen con menos frecuencia y generan una gran cantidad de entradas de registro al mismo tiempo, es más difícil identificar el inicio de un incidente.
  • Los picos de alta simultaneidad en las solicitudes de tokens durante las ejecuciones por lotes aumentan la probabilidad de alcanzar los límites de frecuencia o experimentar errores de autenticación intermitentes.

Comportamiento de los tokens durante las pruebas

Ten en cuenta cómo se comportan los tokens de actualización según el estado de publicación de tu proyecto de Google Cloud:

  • Modo de prueba: Si tu pantalla de consentimiento de OAuth está configurada con un estado de publicación de "Prueba", los tokens de actualización emitidos se basan en el tiempo y vencen después de 7 días. Durante este período, recibirás un solo token de actualización que seguirá siendo válido y se podrá usar para obtener nuevos tokens de acceso hasta que alcance su fecha de vencimiento.
  • Modo publicado: Una vez que tu app se mueva al estado "En producción", los tokens de actualización, por lo general, no vencen, a menos que se revoquen o no se usen durante un período prolongado (por lo general, seis meses).

Para garantizar una experiencia del usuario sin problemas, asegúrate de publicar tu aplicación antes de que se mueva a un entorno de producción para evitar que los tokens venzan en 7 días.

Genera datos de muestra

Google no proporciona datos de salud de muestra o simulados prepropagados. Para probar tu integración, debes generar tus propios datos de prueba. Usa cualquiera de los siguientes métodos para generar datos de muestra para tus usuarios de prueba:

  • Usa un monitor: Usa un monitor Fitbit, un Pixel Watch o cualquier otro reloj inteligente compatible con la app de Google Health y camina para generar datos de pasos, frecuencia cardíaca y entrenamiento.
  • Habilita el monitoreo móvil: Habilita MobileTrack en la app de Google Health y camina con tu dispositivo móvil.
  • Registra datos de forma manual: Ingresa manualmente las métricas de salud (como el sueño, el peso, el consumo de agua o la ingesta de alimentos) a través de la app de Google Health.
  • Escribe datos con la API: Envía solicitudes de escritura (como POST o PATCH) directamente a los endpoints de API de REST para propagar datos de forma programática. Para obtener más detalles sobre cómo crear y actualizar datos, consulta la documentación de referencia de REST.

Protección integral de la cuenta (API de RISC)

Habilita el uso compartido y la coordinación de riesgos e incidentes (RISC) si quieres recibir notificaciones sobre cambios en los tokens de eventos o la vinculación de cuentas, como cuentas desconectadas o tokens revocados, para limpiar los tokens almacenados y actualizar el estado de conexión de la IU. Habilitar la API de RISC es opcional.

Para habilitar la API de RISC en tu proyecto de Google Cloud, sigue estos pasos:

  1. Abre la página de la API de RISC en la consola de Google Cloud. Asegúrate de que esté seleccionado el proyecto que usas para la API de Google Health.
  2. Lee las Condiciones de RISC y asegúrate de comprender los requisitos.
  3. Haz clic en Habilitar si aceptas las condiciones.

Después de habilitar la API, debes crear y registrar un extremo HTTPS para recibir y validar los tokens de eventos que envía Google.

Para obtener más información sobre la Protección integral de la cuenta y RISC, consulta Protege las cuentas de usuario con la Protección integral de la cuenta.