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 seas un desarrollador existente de la API de Fitbit o un usuario nuevo de 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 deseas usar para la API de Google Health, primero asegúrate de haber accedido 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 Web Server cuando te pregunte "¿Desde dónde llamas?".
  3. Ingresa https://www.google.com como el valor de URIs de redireccionamiento autorizadas. 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 las credenciales en formato JSON en tu máquina local.
Habilita la API y obtén un ID de cliente de OAuth 2.0

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

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

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

Usa proyectos separados 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 a tu proyecto de producción cuando esté todo listo.
  • Usa etiquetas en la consola de Google Cloud para distinguir visualmente tus proyectos por entorno. Para obtener instrucciones, consulta Cómo designar 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 de tu 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 a los que se les debe permitir otorgar permiso a tu app para acceder a sus datos de salud.
  3. Haz clic en Guardar.

Para admitir 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 para la verificación de apps con OAuth.

Agregar permisos

Debes especificar los alcances a los 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 "Google Health API". Selecciona los permisos que necesitas para tu aplicación.
  3. Después de seleccionar todos los alcances 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 solicitarle 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 autorización de permisos de acceso, incluso si todos los permisos se otorgaron previamente 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 alcances que necesita tu aplicación. Esto debe incluir los alcances 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 del 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 alcances con prompt=consent agregado:

    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 mostrará una página de consentimiento en la que se enumeran todos los alcances 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 abarcan el conjunto completo de permisos.

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

Bibliotecas cliente de OAuth2

La lista de bibliotecas cliente de OAuth2 disponibles que se usan para la integración con 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, siempre usa navegadores del sistema (como pestañas personalizadas de Chrome en Android o ASWebAuthenticationSession en iOS) y nunca uses WebViews integradas, que bloquean las llaves de acceso y dañan los flujos de Google OAuth. Revisa las prácticas recomendadas de Acceder con Google para obtener orientación.

Antes de que un usuario complete el flujo de consentimiento de OAuth 2.0 de Google en tu app, debe acceder a la app para dispositivos móviles de Google Health para vincular Google Health a 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 activo de Google Health 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 de Google Health para dispositivos móviles desde Google Play Store o App Store de Apple.
  2. Presiona Acceder con Google y selecciona la Cuenta de Google que quieras conectar a tu app.
  3. Sigue las instrucciones en la app para crear un nuevo perfil de Google Health o sigue los pasos para migrar una cuenta de Fitbit y trasladar 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 el manejo de 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 la reautenticación constante del usuario, tu aplicación debe usar un token de actualización. Para obtener detalles completos sobre la implementación, incluidas las solicitudes HTTP y los parámetros específicos que se requieren, 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 extremo de token de Google OAuth 2.0. El siguiente fragmento 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": "refresh-token",
  "refresh_token_expires_in": 112154
}

Cuándo actualizar un token

Actualiza los tokens de acceso a pedido como parte de la progresión natural de la sesión activa de un usuario cuando los tokens de acceso vencen o están cerca de vencer. Evita actualizar los tokens en lotes (por ejemplo, usando un trabajo o servicio cron programado para actualizar los tokens de todos los usuarios en un horario fijo).

No se recomienda actualizar los tokens en lotes por los siguientes motivos:

  • La actualización por lotes impide alinear las actualizaciones de tokens con los patrones de sincronización de usuarios activos. Si bien puedes usar la llamada Get Devices para ver la última hora de 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 al mismo tiempo. La actualización de tokens de forma individual durante la progresión natural de las sincronizaciones de usuarios aísla el impacto de las fallas transitorias en un solo usuario.
  • Es más difícil diagnosticar problemas con los trabajos por lotes. Debido a que las solicitudes por lotes ocurren con menos frecuencia y generan una gran cantidad de entradas de registro de una sola vez, 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 del token 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 "En prueba", los tokens de actualización que se emiten 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 utilizable para obtener nuevos tokens de acceso hasta que llegue a su fecha de vencimiento.
  • Modo publicado: Una vez que tu app se mueve al estado "En producción", los tokens de actualización generalmente no vencen, a menos que se revoquen o permanezcan sin usar 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 completados previamente. 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 seguimiento de actividad móvil: Habilita MobileTrack en la app de Google Health y camina con tu dispositivo móvil.
  • Registra datos manualmente: Ingresa manualmente métricas de salud (como sueño, peso, ingesta de agua o 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 extremos de la API de REST para completar datos de forma programática. Para obtener más detalles sobre cómo crear y actualizar puntos de 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 deseas recibir notificaciones sobre los cambios en los tokens de eventos o la vinculación de cuentas, como las cuentas desconectadas o los tokens revocados, para limpiar los tokens almacenados y actualizar el estado de la conexión de la IU. Habilitar la API de RISC es opcional.

Para habilitar la API de RISC en tu proyecto de Google Cloud, haz lo siguiente:

  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 del 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.