La API de Google Health es una nueva API creada desde cero que permite a los desarrolladores consultar los datos de los usuarios de Fitbit. No se trata solo de una actualización, sino de un movimiento estratégico para garantizar que tus apps sean seguras, confiables y estén listas para los avances futuros en la tecnología de la salud. La API admite una nueva consola para registrar tus apps, compatibilidad con Google OAuth 2.0, nuevos tipos de datos, un nuevo esquema de extremos y un nuevo formato de respuesta.
Esta guía está diseñada para ayudar a los desarrolladores a migrar sus apps existentes de la API de Fitbit Web a la nueva API de Google Health.
¿Por qué deberías migrar?
Estos son los beneficios de usar la API de Google Health:
- Seguridad mejorada: Cumplimiento de las prácticas recomendadas de seguridad de Google, en consonancia con los estándares de seguridad, privacidad e identidad de Google
- Coherencia: Elimina las incoherencias heredadas en los formatos de datos, las zonas horarias, las unidades de medida y el manejo de errores para brindar una experiencia del desarrollador más intuitiva.
- Escalabilidad y preparación para el futuro: Diseñado para escalar y satisfacer las demandas futuras, y admite protocolos modernos como gRPC.
Migra a tus usuarios
Migrar de la API de Fitbit Web a la API de Google Health es más que una actualización técnica. Tus usuarios deben volver a dar su consentimiento para tu nueva integración debido a que cambiaste la biblioteca de OAuth. No es posible transferir tokens de acceso y tokens de actualización a la API de Google Health para que funcionen. Para ayudarte con la retención de usuarios durante la migración, aquí tienes algunas sugerencias técnicas y estratégicas para lograr una migración exitosa.
La estrategia de biblioteca dual
Como la API de Fitbit Web y la API de Google Health usan diferentes bibliotecas de OAuth2, debes administrar un período de "puente" en el que ambas bibliotecas existan en tu código base.
Administración de autorizaciones paralelas
- Encapsula los clientes: Crea una capa de abstracción o una interfaz para tu "Servicio de salud". Esto permite que el resto de tu app solicite datos sin saber qué biblioteca (OAuth de Fitbit o OAuth de Google) está activa para ese usuario específico.
- Actualización del esquema de la base de datos: Actualiza tu tabla de usuarios para incluir una marca
oauth_type. Por ejemplo, usafitbitpara Fitbit OAuth ygooglepara Google OAuth.- Usuarios nuevos: Se establece de forma predeterminada la API de Google Health y la biblioteca de OAuth de Google. Establece
oauth_typeengoogle. - Usuarios existentes: Permanecerán en la API de Fitbit Web hasta que completen el flujo de nuevo consentimiento. Establece
oauth_typeenfitbit.
- Usuarios nuevos: Se establece de forma predeterminada la API de Google Health y la biblioteca de OAuth de Google. Establece
Flujo de nuevo consentimiento "Step-Up"
En lugar de forzar el cierre de sesión, usa un enfoque de autorización incremental:
- Detect Fitbit Open Source Token: Cuando un usuario de la API de Fitbit Web abre la app, se activa una notificación de "Actualización del servicio".
- Iniciar el flujo de OAuth de Google: Cuando el usuario haga clic en "Actualizar", inicia el flujo de la biblioteca de OAuth2 de Google.
- Reemplazar y revocar: Una vez que se reciba correctamente el token de OAuth de Google, guárdalo en el perfil del usuario, actualiza
oauth_typedefitbitagoogley, si es posible, revoca de forma programática el tokenfitbitanterior para mantener limpio el perfil de seguridad del usuario.
Maximiza la retención de usuarios
El reconsentimiento es la "zona de peligro" para la deserción. Para evitar que los usuarios abandonen la app, sigue estas prácticas recomendadas de UX:
La comunicación "Primero el valor"
No comiences con "Actualizamos nuestra API". Comienza con los beneficios del nuevo sistema respaldado por Google:
- Seguridad mejorada: Menciona la protección de cuentas líder en la industria de Google y la 2FA.
- Confiabilidad: Tiempos de sincronización más rápidos y conexiones de datos más estables
- Feature Gating: Informa a los usuarios de forma gradual que las nuevas funciones y los tipos de datos requieren la actualización.
Smart Timing
- No interrumpas las tareas valiosas: Nunca actives la pantalla de nuevo consentimiento mientras un usuario está en medio de un entrenamiento o registrando comida.
- Fase de "sugerencia": Durante los primeros 30 días, usa un banner que se pueda descartar.
- Fase de "cierre definitivo": Solo se hará obligatorio el nuevo consentimiento después de varias semanas de advertencias, lo que coincidirá con los plazos oficiales de baja de la API de Fitbit Web.
Comparación del flujo de migración
Una distinción visual clara entre los flujos antiguos y los nuevos ayuda a los desarrolladores a comprender dónde se bifurca la lógica.
| Función | API de Fitbit Web (heredada) | API de Google Health (Google-Identity) |
| Biblioteca de autenticación | Estándar de código abierto | Google Identity Services (GIS) o Google Auth |
| Cuentas de usuario | Credenciales heredadas de Fitbit | Cuenta de Google |
| Tipo de token | Acceso y actualización específicos de Fitbit | Tokens de acceso y actualización emitidos por Google |
| Administración del alcance | Permisos amplios | Permisos detallados o incrementales |
Cómo manejar los detalles de la migración de la cuenta
Según la documentación de Fitbit, los usuarios que migran su cuenta a Google generalmente no pierden sus conexiones de terceros de inmediato, pero cambiar la versión de la API es un requisito del desarrollador.
- Check Token Validity: Usa un proceso en segundo plano para verificar si los tokens de Fitbit fallan con errores de "Unauthorized". Esto puede indicar que el usuario migró su cuenta, pero tu app no se actualizó.
- Graceful Failures: Si falla una llamada de OAuth de Fitbit, redirecciona al usuario a una página personalizada de "Volver a conectar Fitbit" que use específicamente el nuevo flujo de OAuth de Google.