Guía de migración

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 futuros avances en tecnología de la salud. La API admite una nueva consola para registrar tus apps, compatibilidad con OAuth 2.0 de Google, 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 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 control 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.

Registro de la app

Todas las apps de las APIs de Google Health deben registrarse con la consola de Google Cloud, que funciona como un centro central para administrar todas tus apps de Google.

Si quieres obtener instrucciones para registrar tu app, sigue los pasos que se indican en Primeros pasos. Estas son las diferencias que notarás cuando registres tus apps.

API web de Fitbit API de Google Health
Vínculos públicos https://dev.fitbit.com/apps https://console.cloud.google.com
Cómo agregar una app nueva Presiona Registrar una app nueva.
  1. Crea un proyecto de Google Cloud
  2. Habilita la API de Google Health
Información básica Campos que debes completar:
  • Nombre de la aplicación
  • Descripción
  • URL del sitio web de la aplicación
  • Organización
  • URL del sitio web de la organización
  • URL de las Condiciones del Servicio
  • URL de la Política de Privacidad
 Campos que debes completar:
  • Nombre de la aplicación
  • Correo electrónico de asistencia
  • Público (interno o externo)
  • Correo electrónico de contacto
  • Ícono de logotipo
  • URL del sitio web de la aplicación
  • URL de la política de privacidad
  • URL de las Condiciones del Servicio
  • Dominio autorizado
Tipos de aplicaciones El desarrollador debe seleccionar lo siguiente:
  • Servidor
  • Cliente
  • Personal
  • Aplicación web
  • Android
  • Extensión de Chrome
  • iOS
  • Televisores
  • App de escritorio
  • Plataforma universal de Windows
ID de cliente Se registra cuando se guarda la configuración de la aplicación Se registran por separado
Tipo de acceso El acceso de lectura y escritura se controla a nivel de la app El acceso de lectura y escritura se controla a nivel del alcance
URLs adicionales
  • URL de redireccionamiento: Es el sitio al que se redirecciona a los usuarios después de que autorizan los permisos.
  • Orígenes autorizados de JavaScript: Es el origen HTTP que aloja la aplicación web.
  • URL de redireccionamiento: Es el sitio al que se redirecciona a los usuarios después de que autorizan los permisos.

Implementación de OAuth

Las apps de la API de Google Health solo admiten las bibliotecas cliente de Google OAuth2. Las bibliotecas cliente están disponibles para frameworks populares, lo que simplifica la implementación de OAuth 2.0. Las diferencias entre las bibliotecas de Google OAuth2 y las bibliotecas de OAuth2 de código abierto son las siguientes:

API web de Fitbit API de Google Health
Compatibilidad con la biblioteca de OAuth2 Código abierto Bibliotecas cliente de Google OAuth2
Funcionalidad Incongruente en las diferentes plataformas Coherencia en todas las plataformas
URL de autorización https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
URL del token https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Duración del token de acceso 8 horas 1 hora
Tamaño del token de acceso 1,024 bytes 2,048 bytes
Token de actualización Los tokens de actualización se generan cuando se usa el flujo de otorgamiento de código de autorización. Solo se puede generar 1 token de actualización para un usuario. Los tokens nunca vencen y solo se pueden usar una vez. Para generar un token de actualización, la cadena de autorización debe contener el parámetro de consulta "access_type=offline". Se pueden crear varios tokens de actualización para un solo usuario. Los tokens de actualización pueden basarse en el tiempo. Vencerán si no se usan en 6 meses, si el usuario otorgó acceso basado en el tiempo o si la app está en modo de "Prueba". Consulta Vencimiento del token de actualización para obtener más detalles.
Token Response La respuesta JSON contiene lo siguiente:
  • token de acceso
  • Vencimiento del token de acceso
  • permisos
  • Tipo de token
  • token de actualización
  • ID de usuario
 La respuesta JSON contiene lo siguiente:
  • token de acceso
  • Vencimiento del token de acceso
  • permisos
  • Tipo de token
  • token de actualización

Para obtener el ID de usuario, usa el extremo users.getIdentity.

Los usuarios de Fitbit deben volver a dar su consentimiento para tu nueva integración, ya que tu app usa una biblioteca de OAuth diferente. No es posible transferir tokens de acceso y tokens de actualización a la API de Google Health para que funcionen.

Permisos

Debes actualizar tu solicitud de autorización para usar los alcances de la API de Google Health. Los alcances definen si tu app admite operaciones de lectura o escritura. No uses permisos que no sean necesarios para tu app. Siempre puedes agregar más permisos más adelante si cambia el diseño de tu app.

Los permisos de la API de Google Health son URLs HTTP que comienzan con https://www.googleapis.com/auth/googlehealth.{scope}. Por ejemplo, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Asignaciones de alcance

A continuación, se muestra cómo se asignan los permisos de la API de Fitbit Web a los permisos de la API de Google Health:

Tabla: Asignaciones de alcance de la API web de Fitbit a la API de Google Health
Permisos de la API de Fitbit Web Permisos de las APIs de Google Health
actividad .activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness .activity_and_fitness
.activity_and_fitness.readonly
Frecuencia cardíaca .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
ubicación .location.readonly
nutrición .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
perfil .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
configuración .settings
.settings.readonly
sleep .sleep
.sleep.readonly
temperatura .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
peso .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

Tipos de datos

A continuación, se incluye una lista de los tipos de datos de la API de Google Health y cómo se asignan a la API de Fitbit Web.

Tabla: Asignaciones de tipos de datos de la API web de Fitbit a la API de Google Health
Tipo de datos de la API de Fitbit Web Tipo de datos de la API de Google Health
  ID de extremo
Minutos en zona activa Minutos en Zona activa
  active-zone-minutes
Contiene cambios en los niveles de actividad del usuario Nivel de actividad
  activity-level
Elevación Altitud
  altitude
Grasa corporal Grasa corporal
  body-fat
caloriesOut en cada zona de frecuencia cardíaca Calorías en la zona de frecuencia cardíaca
  calories-in-heart-rate-zone
Resumen del VFC Variabilidad del ritmo cardíaco diaria
  daily-heart-rate-variability
Resumen de SpO2 Saturación de oxígeno diaria
  daily-oxygen-saturation
Frecuencia cardíaca en reposo Frecuencia cardíaca en reposo diaria
  daily-resting-heart-rate
Temperatura cutánea Derivaciones diarias de la temperatura durante el sueño
  daily-sleep-temperature-derivations
Distancia Distancia
  distance
Actividad grabada Ejercicio
  exercise
Pisos Pisos
  floors
Frecuencia cardíaca Frecuencia cardíaca
  heart-rate
VFC intradía Variabilidad de la frecuencia cardíaca
  heart-rate-variability
SpO2 intradía Saturación de oxígeno
  oxygen-saturation
Valor del VO2 máx. cuando el usuario corre VO2 máx. en carreras
  run-vo2-max
Serie temporal de minutos de actividad sedentaria Período sedentario
  sedentary-period
Sueño Sueño
  sleep
Pasos Pasos
  steps
Actividad caloriesOut Calorías totales
  total-calories
Valor de VO2 máx. VO2 máx.
  vo2-max
Peso Peso
  weight

Extremos

Los extremos de REST adoptan una sintaxis coherente para todos los tipos de datos.

  • Extremo de servicio: La URL HTTP base cambia a https://health.googleapis.com.
  • Sintaxis del extremo: La API de Google Health admite una cantidad limitada de extremos, que pueden usar la mayoría de los tipos de datos admitidos. Esto proporciona una sintaxis coherente para todos los tipos de datos y facilita el uso de los extremos.
  • Identificador de usuario: Se debe especificar el ID de usuario o me en la sintaxis del extremo. Cuando se usa, el ID del usuario se infiere del token de acceso.

Ejemplo: A continuación, se muestra un ejemplo del extremo GET Profile llamado con la API de Google Health

GET https://health.googleapis.com/v4/users/me/profile

Asignaciones de extremos

Consulta la tabla Disponibilidad de tipos de datos para obtener una lista de los tipos de datos disponibles y los métodos de API que admiten.

Tipo de extremo de la API web de Fitbit API de Google Health
GET (Log | Summary | Daily Summary) cuando solicitas datos de un solo día Método dailyRollup con windowSize = 1 día
GET (intradía) cuando solicitas datos detallados Método list
GET (series temporales) por fecha o intervalo Método rollUp o dailyRollUp que incluye un período
GET (lista de registros) Método list
Registros de CREATE y UPDATE Método patch
Borrar registros Método batchDelete
GET Profile users.getProfile devuelve la información específica del usuario.
users.getSettings devuelve las unidades y las zonas horarias del usuario.
ACTUALIZA el perfil users.updateProfile modifica la información específica del usuario.
users.updateSettings modifica las unidades y las zonas horarias del usuario.
Obtener el ID de usuario users.getIdentity devuelve el ID de usuario heredado de Fitbit y el ID de usuario de Google.

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 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, usa fitbit para Fitbit OAuth y google para Google OAuth.
    • Usuarios nuevos: Se establece de forma predeterminada la API de Google Health y la biblioteca de OAuth de Google. Establece oauth_type en google.
    • Usuarios existentes: Sigan usando la API de Fitbit Web hasta que completen el flujo de nuevo consentimiento. Establece oauth_type en fitbit.

Flujo de nuevo consentimiento "Step-Up"

En lugar de forzar el cierre de sesión, usa un enfoque de autorización incremental:

  1. 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".
  2. Iniciar el flujo de OAuth de Google: Cuando el usuario haga clic en "Actualizar", inicia el flujo de la biblioteca de OAuth2 de Google.
  3. Reemplazar y revocar: Una vez que se recibe correctamente el token de OAuth de Google, guárdalo en el perfil del usuario, actualiza oauth_type de fitbit a google y, si es posible, revoca de forma programática el token fitbit anterior para mantener limpio el perfil de seguridad del usuario.

Maximiza la retención de usuarios

El reconsentimiento es la "zona de peligro" de 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 funciones y los tipos de datos nuevos requieren la actualización.

Smart Timing

  • No interrumpas las tareas valiosas: Nunca actives la pantalla de volver a dar el consentimiento mientras un usuario está en medio de un entrenamiento o registrando alimentos.
  • 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 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 Código abierto estándar Google Identity Services (GIS) o Google Auth
Cuentas de usuario Credenciales heredadas de Fitbit Cuenta de Google
Tipo de token Acceso o 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 controlar los detalles de la migración de cuentas

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ó.
  • Errores controlados: 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.

Ejemplo de código

Para migrar de la API de Fitbit Web heredada a la API de Google Health, pasarás de las bibliotecas generales de OAuth2 a la biblioteca de Google Auth. A continuación, se incluye una sugerencia de arquitectura y una implementación de pseudocódigo escrita en JavaScript para controlar este estado de "biblioteca dual".

1. El "interruptor de middleware"

Como no puedes migrar a todos los usuarios a la vez, tu backend debe determinar qué biblioteca usar según el valor de apiVersion actual del usuario almacenado en tu base de datos.

Implementación

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Migra el flujo de UX

Para maximizar la retención, usa un patrón de "Interrupción y actualización". Esto garantiza que el usuario no se vea obligado a volver a acceder hasta que ya esté interactuando con la app.

Lógica de redireccionamiento

Cuando un usuario de la API de Fitbit Web accede a una función específica, se activa la migración:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Transiciones técnicas clave

Cuando escribas tus secuencias de comandos de migración de JavaScript, ten en cuenta estas diferencias:

Función API de Fitbit Web (heredada) API de Google Health (Google-Identity)
Extremo del token https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Biblioteca de autenticación Código abierto estándar Google Auth
Alcance actividad https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID de usuario ID codificado de Fitbit que se muestra en la respuesta de /oauth2/token ID de usuario que se devuelve desde el extremo users.getIdentity

4. Lista de tareas de retención

  • Persistencia de sesión: No borres la sesión anterior de la API de Fitbit Web del usuario hasta que se verifique correctamente el access_token de la API de Google Health y se guarde en tu base de datos.
  • Revocación automática: Una vez que se complete la migración de la API de Google Health, usa una solicitud POST al extremo de revocación heredado de Fitbit: https://api.fitbit.com/oauth2/revoke. Esto garantiza que el usuario no vea permisos de apps "duplicados" en la configuración de Fitbit.
  • Control de errores: Si una llamada a Fitbit devuelve un error 401 Unauthorized, se redirecciona automáticamente al flujo de OAuth de Google en lugar de mostrar un mensaje de error.