La migrazione di Google Fit a Health Connect in Capacitor

The Google Fit to Health Connect migration means replacing every Fit API call in your Capacitor app with Health Connect on Android, and with HealthKit on iOS if you ship there too. Google stopped new Fit sign-ups on May 1, 2024, and supports the Fit APIs only until the end of 2026. This guide maps Fit data types and calls to Health Connect, shows the replacement code with @capgo/capacitor-healthe copre anche la revisione del Console Play associata alle autorizzazioni relative alla salute.

Calendario di deprecazione di Google Fit

La FAQ di migrazione di Google afferma che non esiste un'alternativa alle API di Fit REST API con la stessa forma: gli app di rete si spostano su Health Connect, e le integrazioni cloud si spostano sul Google Health basato sull'account API. Se vedete una data di chiusura precisa citata in qualche posto, verificatela contro la FAQ di Google prima di pianificare attorno a essa.

Cosa cambia quando ti sposti a Health Connect

La più grande modifica del prodotto è il modello centrato sul dispositivo. I dati di Health Connect su un telefono non sono visibili su un altro. Se il tuo app mostra la storia su dispositivi diversi, sincronizza le letture sul tuo backend.

Mappe i tipi di dati Fit a Health Connect

Tipi di Fit senza un equivalente diretto

• Punti cardiaci (com.google.heart_minutese e Minuti di movimento (com.google.active_minutesI Google Fit punteggi. Health Connect conserva i dati bruti, non questi punteggi. Ricomputa il tuo proprio metrica dai ritmi cardiaci e dalle sessioni di esercizio.
• Esempi di attività con tipi di attività per secondo sono sostituiti da sessioni di esercizio con segmenti.
• Esempi di posizione all'interno degli allenamenti diventano ExerciseRoute dati in Health Connect, che richiedono un permesso separato e non sono esposti dal plugin.
• Passo, velocità e potenza esistono in Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) ma non sono coperti dai tipi del plugin. Se dipendi da loro, un piccolo metodo nativo personalizzato è la strada più veloce.

Verifica prima di scrivere code: elenca tutti DataType e ogni API che chiami (Storia, Registrazione, Sessioni, Sensori, Configurazione, REST), e segnala ogni uno come mappato, ricomputato o eliminato.

Passo 1: Rimuovi Google Fit

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

• Elimina com.google.android.gms:play-services-fitness e, se utilizzato solo per Fit, play-services-auth da build.gradle.
• Elimina il client OAuth Fit da Google Cloud e i permessi di fitness dalla schermata di consenso.
• Rimuovi il vecchio plugin di Google Fit della community Capacitor che hai utilizzato, quindi esegui bunx cap sync.

Mantieni il Fit code in una branch fino a quando la nuova versione non è live, in modo da poter esportare i dati storici se gli utenti lo chiedono.

Passo 2: Installa il plugin di salute

bun add @capgo/capacitor-health
bunx cap sync

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

Configurazione Android

Il plugin combina le autorizzazioni di lettura e scrittura di Health Connect per i suoi tipi supportati nel tuo manifesto, più l' <queries> entry per il pacchetto di Health Connect e l'attività di giustificazione delle autorizzazioni.

1. Devi fornire una politica di privacy. Health Connect l'apre dalla scheda delle autorizzazioni. Puoi aggiungere android/app/src/main/assets/public/privacypolicy.htmlo impostare una URL in android/app/src/main/res/values/strings.xml:

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

2. Limitare le autorizzazioni. Google Play verifica ogni autorizzazione di Health Connect che dichiari. Se leggi solo i passi e il ritmo cardiaco, rimuovi il resto con tools:node="remove":

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

3. Aggiungi accesso alla cronologia se ne hai bisogno. 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" />

impostazione iOS

Abilita la capacità HealthKit in Xcode e aggiungi 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>

Verifica la disponibilità: Step 3

Google Fit funzionava ovunque esistevano i servizi Play. 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 schermata di spiegazione breve prima di reindirizzare. Gli utenti che non hanno mai sentito parlare di Health Connect si confondono quando la Play Store si apre senza preavviso.

Passo 4: Sostituisci OAuth con autorizzazioni

Il flusso Fit era: Google Sign-In, richiesta di autorizzazioni per la salute, poi chiamare le API. Il nuovo flusso è un foglio di autorizzazione unico:

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 dati e l'utente può concedere qualsiasi sottinsieme. Utilizza checkAuthorization con gli stessi opzioni ad ogni avvio dell'app, perché gli utenti possono revocare l'accesso nelle impostazioni di Health Connect in qualsiasi momento. Su iOS, HealthKit nasconde le negazioni di lettura per motivi di privacy, quindi un risultato vuoto può significare "nessun dato" o "nessun accesso".

Passo 5: Sostituisci la Storia API

A Fit readData Chiedi campioni crudi 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, chestStrapSostituisci gli oggetti di origine dei dati di Fit e utilizzali per preferire i dati dell'orologio rispetto a quelli del telefono quando entrambi esistono.

Passo 6: Sostituisci le letture raggruppate e aggregate

Fit’s 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

Aggiungi sempre i passi invece di sommare i campioni raw. Health Connect elimina i dati sovrapposti da più app durante l'aggregazione, e le somme raw spesso contano i passi due volte quando un orologio e un telefono registrano entrambi i passi.

Passo 7: Sostituisci le Sessioni API

Sessioni Fit si mappano 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

Richiedi workouts in read permissions first. The plugin reads workouts but does not write exercise sessions, so if your app records workouts, write the underlying samples (distance, calories, heart rate) and keep the session itself in your backend, or add a native method for ExerciseSessionRecord.

Passaggio 8: Sostituisci gli insert

Fit’s 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(),
});

Deve essere utilizzato il valore predefinito di ogni tipo (chilogrammi, metri, chilocalorie, bpm). L' metadata opzione viene ignorata da Health Connect.

Passa la revisione di Google Play: passo 9

I permessi di salute scatenano una revisione aggiuntiva:

1. In Console di Play, apri Contenuto dell'app e completa la Health apps dichiarazione e il modulo di autorizzazione di Health Connect. Giustifica ogni autorizzazione richiesta.
2. Assicurati che la politica sulla privacy collegata in Console di Play e quella mostrata nella scheda di Health Connect descrivano l'uso dei dati di salute.
3. Aggiorna la Sicurezza dei dati form: dati di salute e fitness, raccolti o meno, condivisi o meno.
4. Invia un build che dichiari solo le autorizzazioni che hai giustificato. Le autorizzazioni dichiarate in più sono la causa più comune di rifiuto.

Pianifica la revisione per durare più a lungo di un normale aggiornamento. Invia la migrazione come rilascio separato, non mescolato con funzionalità non correlate.

Passo 10: Migra le aspettative degli utenti

• Ora i dati della storia vengono da Health Connect, e i dati più antichi potrebbero essere limitati a 30 giorni fino a quando non concederete l'accesso alla storia.
• Se il tuo app utilizzava Fit come sincronizzazione cloud, sposta quella responsabilità sul tuo backend adesso.
• Elimina i pulsanti "Connetti Google Fit" e rinominali "Connetti Health Connect" su Android e "Connetti Apple Health" su iOS.

Risolvere i problemi

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

: la finestra delle autorizzazioni non compare mai: la autorizzazione non è dichiarata nel manifesto combinato, o hai rimossa con tools:node="remove"Controlla. android/app/build/intermediates/merged_manifests.

Ritorna solo i dati per 30 giorni.: richiedi requestHistoryAccess: true e dichiara READ_HEALTH_DATA_HISTORY.

I passi totali sono più alti di Google Fit: hai sommato campioni raw. Utilizza queryAggregated.

Risultati vuoti su iOS: o no dati o permesso di lettura negato. HealthKit non ti dice quale.

Console di gioco rifiuta l'aggiornamento: elimina le autorizzazioni Health Connect non dichiarate o non giustificate e ripresenta con una giustificazione chiara.

Consegna la migrazione in fasi

La parte nativa (plugin, manifesto, capacità HealthKit) richiede una versione di store. Dopo di che, le query, l'interfaccia utente e la mappatura dei dati sono JavaScript, che puoi iterare con Capgo aggiornamenti in tempo reale mentre gli utenti testano il nuovo flusso. Se anche leggi i dati sensori in tempo reale, consulta la nostra guida a costruire un monitor del ritmo cardiaco con Capacitor, e i documentazione plugin salute Crediti dell'articolo