La API de Google Health es una nueva API creada desde cero que permite a los desarrolladores consultar datos de 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 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.
La 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 realizar la migración?
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 y de identidad de Google.
- Coherencia: Elimina las inconsistencias heredadas en los formatos de datos, las zonas horarias, las unidades de medida y el manejo de errores para una experiencia del desarrollador más intuitiva.
- Escalabilidad y preparación para el futuro: Diseñada para adaptarse a las demandas futuras y admite protocolos modernos como gRPC.
Migra a tus usuarios
La migración 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 al cambio de la biblioteca de OAuth. No es posible transferir tokens de acceso y tokens de actualización a la API de Google Health y que funcionen. Para ayudar con la retención de usuarios durante la migración, aquí tienes algunas sugerencias técnicas y estratégicas para una migración exitosa.
La estrategia de biblioteca dual
Como la API web de Fitbit y Google Health usan diferentes bibliotecas de OAuth2, debes administrar un período de "puente" en el que ambas bibliotecas existan en tu base de código.
Administración de autorización paralela
- Encapsula clientes: Crea una capa o interfaz de abstracción para tu "Servicio de salud". Esto permite que el resto de tu app solicite datos sin saber qué biblioteca (Fitbit OAuth o Google OAuth) está activa para ese usuario específico.
- Actualización del esquema de la base de datos: Actualiza tu tabla de usuarios para incluir una
oauth_typemarca. Por ejemplo, usafitbitpara Fitbit OAuth ygooglepara Google OAuth.- Usuarios nuevos: Establece como predeterminadas la API de Google Health y la biblioteca de Google OAuth. Establece
oauth_typeengoogle. - Usuarios existentes: Mantén la API de Fitbit Web hasta que completen
el flujo de consentimiento. Establece
oauth_typeenfitbit.
- Usuarios nuevos: Establece como predeterminadas la API de Google Health y la biblioteca de Google OAuth. Establece
El flujo de consentimiento "Step-Up"
En lugar de forzar el cierre de sesión, usa un enfoque de autorización incremental:
- Detecta el token de código abierto de Fitbit: Cuando un usuario de la API de Fitbit Web abra la app, activa una notificación de "Actualización del servicio".
- Inicia el flujo de Google OAuth: Cuando el usuario haga clic en "Actualizar", inicia el flujo de la biblioteca de Google OAuth2.
- Reemplaza y revoca: Una vez que se reciba correctamente el token de Google OAuth, guárdalo en el perfil del usuario, actualiza el
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 consentimiento es la "zona de peligro" para la rotación. Para evitar que los usuarios abandonen la app, sigue estas prácticas recomendadas de UX:
La comunicación "Value-First"
No comiences con "Actualizamos nuestra API". Comienza con los beneficios del nuevo sistema respaldado por Google:
- Seguridad mejorada: Menciona la protección de cuentas y la 2FA líderes en la industria de Google.
- Confiabilidad: Tiempos de sincronización más rápidos y conexiones de datos más estables.
- Control de funciones: Informa a los usuarios que las nuevas funciones y los tipos de datos requieren la actualización.
Sincronización inteligente
- No interrumpas las tareas de alto valor: Nunca actives la pantalla de consentimiento mientras un usuario está en medio de un entrenamiento o registrando comida.
- La fase de "Nudge": Durante los primeros 30 días, usa un banner que se pueda descartar.
- La fase de "Hard Cutoff": Solo haz que el consentimiento sea obligatorio después de varias semanas de advertencias, que coincidan 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 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 (identidad de Google) |
| Biblioteca de autenticación | Código abierto estándar | Google Identity Services (GIS) / Google Auth |
| Cuentas de usuario | Credenciales heredadas de Fitbit | Cuenta de Google |
| Tipo de token | Acceso / actualización específicos de Fitbit | Tokens de acceso/actualización emitidos por Google |
| Administración del alcance | Permisos amplios | Permisos detallados / incrementales |
Maneja los matices de la migración de cuentas
Según la documentación de Fitbit, los usuarios que migran su cuenta a Google, por lo general, no pierden sus conexiones de terceros de inmediato, pero cambiar la versión de la API es un requisito del desarrollador.
- Verifica la validez del token: Usa un trabajador en segundo plano para verificar si los tokens de Fitbit fallan con errores "No autorizado". Esto puede indicar que el usuario migró su cuenta, pero tu app no se actualizó.
- Errores correctos: Si falla una llamada de Fitbit OAuth, redirecciona al usuario a una página personalizada de "Volver a conectar Fitbit" que use específicamente el nuevo flujo de Google OAuth.