Migrazione da Google Fit a Health Connect in Capacitor

La migrazione da Google Fit a Health Connect consiste nel sostituire ogni chiamata API di Fit nella tua app Capacitor con Health Connect su Android, e con HealthKit su iOS se pubblichi anche lì. Google ha interrotto le nuove iscrizioni a Fit il 1° maggio 2024 e supporterà le API di Fit solo fino alla fine del 2026. Questa guida associa i tipi di dati e le chiamate di Fit a Health Connect, mostra la sostituzione di code con @capgo/capacitor-health, e copre la revisione della Play Console che accompagna i permessi relativi alla salute.

Timeline della deprecazione di Google Fit

Le FAQ sulla migrazione di Google dicono che non c'è alternativa alla API REST di Fit con la stessa struttura: le app on-device passano a Health Connect e le integrazioni cloud passano a Google Health API basato sull'account. Se vedi una data di chiusura precisa citata da qualche parte, confrontala con le FAQ di Google prima di pianificare.

Cosa cambia passando a Health Connect

La modifica di prodotto più significativa è il modello device-centric. I dati Health Connect su un telefono non sono visibili su un altro. Se la tua app mostra la cronologia tra più dispositivi, sincronizza le letture sul tuo backend.

Mappare i tipi di dati Fit su Health Connect

Tipi Fit senza un equivalente diretto

• Punti Cuore (com.google.heart_minutes) e Sposta minuti (com.google.active_minutes) erano punteggi di Google Fit. Health Connect memorizza dati grezzi, non questi punteggi. Ricalcola la tua metrica da frequenza cardiaca e sessioni di esercizio.
• Campioni di attività con tipi di attività al secondo vengono sostituiti da sessioni di esercizio con segmenti.
• Campioni di posizione all'interno delle sessioni di allenamento diventano ExerciseRoute dati in Health Connect, che richiede un'autorizzazione separata e non è esposto dal plugin.
• Cadenza, velocità e potenza esistono in Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) ma non sono coperti dai tipi del plugin. Se ci fai affidamento, un piccolo metodo nativo custom è la via più veloce.

Fai un audit prima di scrivere code: elenca ogni DataType e ogni API che chiami (History, Recording, Sessions, Sensors, Config, REST), e segna ognuno come mappato, ricalcolato o scartato.

Passaggio 1: Rimuovi Google Fit

Rimuovi l'integrazione Fit dal tuo progetto Android e dal JavaScript:

• Rimuovi com.google.android.gms:play-services-fitness e, se lo usi solo per Fit, play-services-auth da build.gradle.
• Rimuovi il client OAuth di Fit da Google Cloud e gli scope fitness dalla tua schermata di consenso.
• Disinstalla il vecchio plugin Capacitor della community per Google Fit che usavi, quindi esegui bunx cap sync.

Mantieni il Fit code in un branch finché la nuova versione non è live, così potrai esportare i dati storici se richiesto dagli utenti.

Passaggio 2: Installa il plugin health

bun add @capgo/capacitor-health
bunx cap sync

@capgo/capacitor-health supporta Capacitor 8, usa Health Connect su Android e HealthKit su iOS, e richiede Android minSdk 26.

Configurazione Android

Il plugin integra nel manifest i permessi di lettura e scrittura di Health Connect per i tipi supportati, oltre alla <queries> voce per il pacchetto Health Connect e l'activity per la spiegazione dei permessi. Devi:

1. Fornisci una privacy policy. Health Connect la apre dalla schermata dei permessi. Aggiungi android/app/src/main/assets/public/privacypolicy.html, oppure imposta un URL in android/app/src/main/res/values/strings.xml:

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

2. Riduci i permessi. Google Play revisiona ogni permesso Health Connect dichiarato. Se leggi solo passi e frequenza cardiaca, rimuovi il resto con tools:node="remove":

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

3. Aggiungi l'accesso alla cronologia se ti serve. Health Connect limita le letture a circa gli ultimi 30 giorni, a meno che l'utente non conceda READ_HEALTH_DATA_HISTORY:

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

Setup iOS

Abilita la funzionalità HealthKit in Xcode e aggiungi le stringhe di utilizzo a 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>

Passaggio 3: Verifica disponibilità

Google Fit funzionava ovunque fossero presenti i Play services. Health Connect potrebbe mancare su Android 13 e versioni precedenti, o richiedere un aggiornamento.

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;
}

Mostra una breve schermata esplicativa prima del reindirizzamento. Gli utenti che non hanno mai sentito parlare di Health Connect restano confusi quando il Play Store si apre senza preavviso.

Passaggio 4: Sostituisci OAuth con i permessi

Il vecchio flusso era: Google Sign-In, richiesta degli scope fitness e chiamata alle API. Il nuovo flusso prevede un unico foglio di autorizzazione:

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
}

I permessi sono per tipo di dato e l'utente può concedere qualsiasi sottoinsieme. Usa checkAuthorization con le stesse opzioni a ogni avvio dell'app, poiché gli utenti possono revocare l'accesso nelle impostazioni di Health Connect in qualsiasi momento. Su iOS, HealthKit nasconde i rifiuti di lettura per motivi di privacy, quindi un risultato vuoto può significare "nessun dato" o "nessun accesso".

Passaggio 5: Sostituisci le letture History API

Un Fit readData per i campioni raw diventa 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 e, su Android, deviceType (watch, phone, chestStrap, and so on) replace Fit’s data source objects. Use them to prefer watch data over phone data when both exist.

Passaggio 6: Sostituisci le letture bucketed e aggregate

di Fit bucketByTime più aggregate diventa 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

Aggrega sempre i passi invece di sommare i campioni grezzi. Health Connect deduplica i dati sovrapposti da più app durante l'aggregazione, e le somme grezze spesso contano due volte quando sia il watch che il telefono registrano i passi.

Passaggio 7: Sostituisci le Sessions API

Le sessioni Fit corrispondono alle sessioni di esercizio:

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

Richiesta workouts nella read prima i permessi. Il plugin legge gli allenamenti ma non scrive le sessioni di allenamento; quindi, se la tua app registra allenamenti, scrivi i campioni sottostanti (distanza, calorie, frequenza cardiaca) e conserva la sessione nel tuo backend, oppure aggiungi un metodo nativo per ExerciseSessionRecord.

Passaggio 8: Sostituisci gli insert

di Fit insertData diventa 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(),
});

I valori devono usare l'unità predefinita per ogni tipo (chilogrammi, metri, chilocalorie, bpm). L'opzione metadata viene ignorata da Health Connect.

Passaggio 9: Supera la revisione di Google Play

I permessi Health attivano una revisione aggiuntiva:

1. In Play Console, apri Contenuti dell'app e completa il App per la salute dichiarazione e il modulo dei permessi Health Connect. Giustifica ogni permesso richiesto.
2. Assicurati che la privacy policy collegata in Play Console e quella mostrata nel foglio Health Connect descrivano l'uso dei dati sanitari.
3. Aggiorna il Sicurezza dei dati form: dati relativi alla salute e al fitness, raccolti o meno, condivisi o meno.
4. Invia un build che dichiari solo i permessi giustificati. L'aggiunta di permessi non necessari è la causa più comune di rifiuto.

Metti in conto che la revisione richieda più tempo di un aggiornamento normale. Rilascia la migrazione come release separata, non mischiarla a feature non correlate.

Passaggio 10: Migrare le aspettative degli utenti

• Informa gli utenti che ora la cronologia proviene da Health Connect e che i dati più vecchi potrebbero essere limitati a 30 giorni finché non concedono l'accesso alla cronologia.
• Se la tua app usava Fit per la sincronizzazione cloud, sposta subito questa responsabilità sul tuo backend.
• Rimuovi i pulsanti “Connect Google Fit” e rinominali in “Connect Health Connect” su Android e “Connect Apple Health” su iOS.

Risoluzione problemi

isAvailable() restituisce false su Android 13: Health Connect non è installato o è obsoleto. Chiama openHealthConnectSettings().

Il prompt dei permessi non appare mai: il permesso non è dichiarato nel manifest unificato, oppure è stato rimosso con tools:node="remove". Controlla android/app/build/intermediates/merged_manifests.

Le letture restituiscono solo 30 giorni: richiedi requestHistoryAccess: true e dichiara READ_HEALTH_DATA_HISTORY.

I totali dei passi sono superiori a Google Fit: hai sommato i campioni grezzi. Usa queryAggregated.

Risultati vuoti su iOS: non ci sono dati oppure l'accesso è negato. HealthKit non specifica quale dei due.

Play Console rifiuta l'aggiornamento: rimuovi i permessi Health Connect non dichiarati o non giustificati e invia nuovamente con una spiegazione chiara.

Rilascia la migrazione in fasi

La parte nativa (plugin, manifest, capability HealthKit) richiede un rilascio sugli store. Poi query, UI e mapping dei dati sono JavaScript, su cui puoi iterare con Live updates di Capgo mentre gli utenti testano il nuovo flusso. Se leggi anche dati dei sensori in tempo reale, consulta la nostra guida per creare un monitor della frequenza cardiaca con Capacitor, e il Documentazione del plugin Health per ogni tipo di dato.