Migración de Google Fit a Health Connect en Capacitor

La migración de Google Fit a Health Connect implica reemplazar cada llamada de Fit API en tu app Capacitor por Health Connect en Android, y por HealthKit en iOS si también lanzas ahí. Google detuvo los nuevos registros en Fit el 1 de mayo de 2024 y solo dará soporte a las APIs de Fit hasta finales de 2026. Esta guía mapea los tipos de datos y llamadas de Fit a Health Connect, muestra el reemplazo code con @capgo/capacitor-health, y cubre la revisión de Play Console que conlleva el uso de permisos de salud.

Cronograma de depreciación de Google Fit

El FAQ de migración de Google indica que no hay una alternativa al API REST de Fit con la misma estructura: las apps locales pasan a Health Connect y las integraciones en la nube pasan a Google Health API basado en cuenta. Si ves una fecha de cierre específica en algún lugar, verifícala con el FAQ oficial de Google antes de planificar.

Qué cambia al migrar a Health Connect

El mayor cambio es el modelo centrado en el dispositivo. Los datos de Health Connect en un teléfono no son visibles en otro. Si tu app muestra historial entre dispositivos, sincroniza las lecturas con tu propio backend.

Mapear tipos de datos de Fit a Health Connect

tipos de Fit sin equivalente directo

• Puntos de corazón (com.google.heart_minutes) y Minutos en movimiento (com.google.active_minutes) eran métricas de Google Fit. Health Connect almacena datos brutos, no estos puntajes. Recalcula tu propia métrica usando la frecuencia cardíaca y las sesiones de ejercicio.
• Muestras de actividad con tipos de actividad por segundo se reemplazan por sesiones de ejercicio con segmentos.
• Muestras de ubicación dentro de entrenamientos pasan a ser ExerciseRoute datos en Health Connect, que requieren un permiso aparte y no están expuestos por el plugin.
• Cadencia, velocidad y potencia existen en Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) pero no están cubiertos por los tipos del plugin. Si dependes de ellos, crear un pequeño método nativo personalizado es el camino más rápido.

Audita antes de escribir code: enumera cada DataType y cada API que llames (History, Recording, Sessions, Sensors, Config, REST), y marca cada uno como mapeado, recomputado o descartado.

Paso 1: Eliminar Google Fit

Elimina la integración de Fit de tu proyecto de Android y de JavaScript:

• Elimina com.google.android.gms:play-services-fitness y, si solo se usa para Fit, play-services-auth de build.gradle.
• Elimina el cliente OAuth de Fit de Google Cloud y los scopes de fitness de tu pantalla de consentimiento.
• Desinstala el antiguo plugin de la comunidad de Google Fit Capacitor que usabas, luego ejecuta bunx cap sync.

Mantén el code de Fit en una rama hasta que la nueva versión esté live, para poder exportar datos históricos si los usuarios lo piden.

Paso 2: Instalar el plugin de salud

bun add @capgo/capacitor-health
bunx cap sync

@capgo/capacitor-health soporta Capacitor 8, usa Health Connect en Android y HealthKit en iOS, y requiere Android minSdk 26.

Configuración de Android

El plugin integra los permisos de lectura y escritura de Health Connect para los tipos compatibles en tu manifest, además de la <queries> entrada para el paquete de Health Connect y la actividad de justificación de permisos. Debes:

1. Proporcionar una política de privacidad. Health Connect la abre desde la hoja de permisos. Puedes añadir android/app/src/main/assets/public/privacypolicy.htmlo configurar una URL en android/app/src/main/res/values/strings.xml:

<string name="health_connect_privacy_policy_url">https://example.com/privacy</string>

2. Reducir permisos. Google Play revisa cada permiso de Health Connect que declares. Si solo lees pasos y ritmo cardíaco, elimina el resto con tools:node="remove":

<uses-permission
    android:name="android.permission.health.WRITE_BLOOD_GLUCOSE"
    tools:node="remove" />

3. Añade acceso al historial si lo necesitas. Health Connect limita las lecturas a unos 30 días, a menos que el usuario conceda READ_HEALTH_DATA_HISTORY:

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

iOS setup

Habilita la capacidad HealthKit en Xcode y añade los usage strings en Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>Show your steps and workouts in the app.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>Save the workouts you record in the app.</string>

Paso 3: Comprobar disponibilidad

Google Fit funcionaba donde hubiera Play services. Health Connect puede no estar disponible en Android 13 o versiones anteriores, o requerir una actualización.

import { Health } from '@capgo/capacitor-health';

export async function ensureHealthAvailable() {
  const result = await Health.isAvailable();
  if (result.available) return true;

  // On Android, send the user to install or update Health Connect
  if (result.platform === 'android') {
    await Health.openHealthConnectSettings();
  }
  console.warn('Health store unavailable:', result.reason);
  return false;
}

Muestra una breve pantalla explicativa antes de redirigir. Los usuarios que no conocen Health Connect se confunden si la Play Store se abre sin previo aviso.

Paso 4: Reemplazar OAuth por permisos

El flujo de Fit era: Google Sign-In, solicitar scopes de fitness y llamar a las APIs. El nuevo flujo es un único panel de permisos:

const status = await Health.requestAuthorization({
  read: ['steps', 'distance', 'calories', 'heartRate', 'sleep', 'workouts'],
  write: ['weight'],
  requestHistoryAccess: true, // Android only
});

if (status.readDenied.length > 0) {
  // explain what will not work and offer openHealthConnectSettings()
}
if (status.historyAccessAvailable === false) {
  // provider too old: only the last 30 days are readable
}

Los permisos son por tipo de dato y el usuario puede conceder solo algunos. Usa checkAuthorization con las mismas opciones al iniciar cada app, ya que los usuarios pueden revocar el acceso en los ajustes de Health Connect en cualquier momento. En iOS, HealthKit oculta las denegaciones de lectura por privacidad, por lo que un resultado vacío puede significar “sin datos” o “sin acceso”.

Paso 5: Reemplazar lecturas de API de History

A Fit readData para muestras raw se convierte en readSamples:

const end = new Date();
const start = new Date(end.getTime() - 24 * 60 * 60 * 1000);

const { samples } = await Health.readSamples({
  dataType: 'heartRate',
  startDate: start.toISOString(),
  endDate: end.toISOString(),
  limit: 500,
  ascending: true,
});

for (const s of samples) {
  console.log(s.startDate, s.value, s.unit, s.sourceName, s.deviceType);
}

sourceName y, en Android, deviceType (watch, phone, chestStrap, etc.) reemplazan los objetos de fuente de datos de Fit. Úsalos para priorizar los datos del watch sobre los del teléfono cuando ambos existan.

Paso 6: Reemplazar lecturas agrupadas y agregadas

de Fit bucketByTime más aggregate pasa a ser queryAggregated:

const { samples: daily } = await Health.queryAggregated({
  dataType: 'steps',
  startDate: new Date(Date.now() - 7 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',          // 'hour' | 'day' | 'week' | 'month'
  aggregation: 'sum',
});

const { samples: hr } = await Health.queryAggregated({
  dataType: 'heartRate',
  bucket: 'hour',
  aggregation: ['min', 'average', 'max'],
  startDate: new Date(Date.now() - 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
});
// hr[i].values.min, hr[i].values.average, hr[i].values.max

Agrega siempre los pasos en lugar de sumar muestras brutas. Health Connect elimina duplicados de datos superpuestos de varias apps durante la agregación; las sumas brutas suelen duplicar datos cuando un reloj y un teléfono registran pasos.

Paso 7: Reemplazar las sesiones de API

Las sesiones de Fit se mapean a sesiones de ejercicio:

const { workouts, anchor } = await Health.queryWorkouts({
  workoutType: 'running',
  startDate: new Date(Date.now() - 30 * 86_400_000).toISOString(),
  endDate: new Date().toISOString(),
  limit: 50,
});

for (const w of workouts) {
  console.log(w.workoutType, w.duration, w.totalDistance, w.totalEnergyBurned);
}
// pass `anchor` back to fetch the next page

Solicita workouts en read permisos primero. El plugin lee entrenamientos pero no escribe sesiones de ejercicio; si tu app registra entrenamientos, escribe las muestras subyacentes (distancia, calorías, ritmo cardíaco) y mantén la sesión en tu backend, o añade un método nativo para ExerciseSessionRecord.

Paso 8: Reemplazar los inserts

de Fit insertData pasa a ser saveSample:

await Health.saveSample({
  dataType: 'weight',
  value: 72.4, // kilograms
  startDate: new Date().toISOString(),
});

await Health.saveSample({
  dataType: 'bloodPressure',
  value: 120,
  systolic: 120,
  diastolic: 80,
  startDate: new Date().toISOString(),
});

Los valores deben usar la unidad por defecto de cada tipo (kilogramos, metros, kilocalorías, bpm). La metadata opción es ignorada por Health Connect.

Paso 9: Superar la revisión de Google Play

Los permisos de salud activan una revisión adicional:

1. En Play Console, abre Contenido de la app y completa la Apps de salud declaración y el formulario de permisos de Health Connect. Justifica cada permiso que solicites.
2. Asegúrate de que la política de privacidad en Play Console y la de la ficha de Health Connect describan el uso de datos de salud.
3. Actualiza el Data safety form: datos de salud y fitness, recopilados o no, compartidos o no.
4. Envía un build que solo declare los permisos justificados. Los permisos extra son el motivo de rechazo más común.

Prevé que la revisión tarde más de lo habitual. Lanza la migración como un release independiente, sin mezclarla con otras funciones.

Paso 10: Gestionar las expectativas del usuario

• Informa a los usuarios que su historial ahora proviene de Health Connect, y que los datos antiguos podrían limitarse a 30 días hasta que concedan acceso al historial.
• Si tu app usaba Fit para la sincronización en la nube, traslada esa responsabilidad a tu backend ahora.
• Elimina los botones “Connect Google Fit” y cámbialos por “Connect Health Connect” en Android y “Connect Apple Health” en iOS.

Solución de problemas

isAvailable() devuelve false en Android 13: Health Connect no está instalado o está desactualizado. Llama a openHealthConnectSettings().

El prompt de permisos nunca aparece: el permiso no está declarado en el manifest fusionado, o lo eliminaste con tools:node="remove". Revisa android/app/build/intermediates/merged_manifests.

Las lecturas solo devuelven 30 días: solicita requestHistoryAccess: true y declara READ_HEALTH_DATA_HISTORY.

Los totales de pasos son mayores que en Google Fit: sumaste las muestras raw. Usa queryAggregated.

Resultados vacíos en iOS: no hay datos o se denegó el permiso de lectura. HealthKit no especifica cuál.

Play Console rechaza la actualización: elimina los permisos de Health Connect no declarados o injustificados y vuelve a enviarla con una justificación clara.

Lanza la migración por etapas

La parte nativa (plugin, manifest, capability de HealthKit) requiere un release en la tienda. Después, las queries, la UI y el mapeo de datos son JavaScript, que puedes iterar con Live Updates de Capgo mientras los usuarios prueban el nuevo flujo. Si también lees datos de sensores en tiempo real, consulta nuestra guía para crear un monitor de ritmo cardíaco con Capacitor, y la documentación del plugin de health para cada tipo de dato.