Migration von Google Fit zu Health Connect in Capacitor

Die Migration von Google Fit zu Health Connect bedeutet, jeden Fit-API-Aufruf in deiner Capacitor-App durch Health Connect auf Android zu ersetzen – und durch HealthKit auf iOS, falls du auch dort veröffentlichen möchtest. Google hat am 1. Mai 2024 neue Fit-Registrierungen eingestellt und unterstützt die Fit-APIs nur noch bis Ende 2026. Dieser Guide ordnet Fit-Datentypen und -Aufrufe Health Connect zu, zeigt den Ersatz-code mit @capgo/capacitor-health, und behandelt die Play-Console-Prüfung, die mit Gesundheitsberechtigungen einhergeht.

Zeitplan für die Google Fit Deprecation

Die Migrations-FAQ von Google besagt, dass es keine Alternative zur Fit REST API mit derselben Struktur gibt: On-Device-Apps wechseln zu Health Connect, Cloud-Integrationen zum accountbasierten Google Health API. Wenn du irgendwo ein genaues Abschaltdatum liest, prüfe es gegen die offizielle FAQ von Google, bevor du dich darauf planst.

Was sich beim Wechsel zu Health Connect ändert

Die größte Produktänderung ist das geräteeigene Modell. Health-Connect-Daten auf einem Telefon sind auf einem anderen nicht sichtbar. Zeigt deine App Historie über mehrere Geräte an, synchronisiere die Messwerte mit deinem eigenen Backend.

Fit-Datentypen auf Health Connect mappen

Fit-Typen ohne direktes Äquivalent

• Herzpunkte (com.google.heart_minutes) und Aktivitätsminuten (com.google.active_minutes) waren Google Fit-Scores. Health Connect speichert Rohdaten, nicht diese Scores. Berechnen Sie Ihre eigene Metrik aus Herzfrequenz und Trainingssitzungen.
• Aktivitätsproben mit sekundengenauen Aktivitätstypen werden durch Übungssitzungen mit Segmenten ersetzt.
• Standortproben in Workouts werden zu ExerciseRoute Daten in Health Connect, die eine separate Berechtigung erfordern und nicht vom Plugin bereitgestellt werden.
• Kadenz, Geschwindigkeit und Leistung existieren in Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord), werden aber nicht von den Plugin-Typen abgedeckt. Wenn du sie benötigst, ist eine kleine eigene native Methode der schnellste Weg.

Audit, bevor du code schreibst: Liste alles auf, DataType auch jeden API, den du aufrufst (History, Recording, Sessions, Sensors, Config, REST), und markiere jedes als gemappt, neu berechnet oder verworfen.

Schritt 1: Google Fit entfernen

Entferne die Fit-Integration aus deinem Android-Projekt und deinem JavaScript:

• Entfernen com.google.android.gms:play-services-fitness und, falls sie nur für Fit genutzt wird, play-services-auth von build.gradle.
• entferne den Fit-OAuth-Client aus der Google Cloud und die Fitness-Scopes von deinem Consent Screen.
• Deinstalliere das alte Community-Google-Fit-Capacitor-Plugin, das du verwendet hast, und führe dann aus: bunx cap sync.

Behalte das Fit-code in einem Branch, bis die neue Version live ist, damit du historische Daten exportieren kannst, falls Nutzer danach fragen.

Schritt 2: Health-Plugin installieren

bun add @capgo/capacitor-health
bunx cap sync

@capgo/capacitor-health unterstützt Capacitor 8, nutzt Health Connect unter Android und HealthKit unter iOS und erfordert Android minSdk 26.

Android-Setup

Das Plugin fügt die Lese- und Schreibberechtigungen von Health Connect für die unterstützten Typen in dein Manifest ein, zusätzlich zur <queries> Eintrag für das Health-Connect-Paket und die Berechtigungs-Begründungs-Aktivität. Du musst:

1. Eine Datenschutzerklärung bereitstellen. Health Connect öffnet es aus dem Berechtigungsdialog. Füge entweder hinzu android/app/src/main/assets/public/privacypolicy.html, oder setze eine URL in android/app/src/main/res/values/strings.xml:

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

2. Berechtigungen reduzieren. Google Play prüft jede deklarierte Health-Connect-Berechtigung. Wenn du nur Schritte und Herzfrequenz liest, entferne den Rest mit tools:node="remove":

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

3. Füge Historienzugriff hinzu, falls benötigt. Health Connect begrenzt Lesezugriffe auf etwa die letzten 30 Tage, es sei denn, der Nutzer erteilt READ_HEALTH_DATA_HISTORY:

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

iOS-Setup

Aktiviere die HealthKit-Fähigkeit in Xcode und füge Nutzungstexte hinzu in 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>

Schritt 3: Verfügbarkeit prüfen

Google Fit funktionierte überall, wo Play-Dienste vorhanden waren. Health Connect fehlt möglicherweise auf Android 13 und älter oder benötigt ein Update.

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

Kurz erklären, bevor weitergeleitet wird. Nutzer, die Health Connect nicht kennen, sind verwirrt, wenn der Play Store ohne Vorwarnung öffnet.

Schritt 4: OAuth durch Permissions ersetzen

Der Fit-Flow war: Google Sign-In, Fitness-Scopes anfordern, dann APIs aufrufen. Der neue Flow ist ein einzelnes Berechtigungs-Blatt:

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
}

Berechtigungen gelten pro Datentyp, und der Nutzer kann jede Teilmenge erteilen. Verwende checkAuthorization mit denselben Optionen bei jedem App-Start, da Nutzer den Zugriff in den Health-Connect-Einstellungen jederzeit widerrufen können. Auf iOS blendet HealthKit Read-Verweigerungen aus Datenschutzgründen aus, sodass ein leeres Ergebnis entweder „keine Daten“ oder „kein Zugriff“ bedeuten kann.

Schritt 5: History-API-Reads ersetzen

Ein Fit readData Der Aufruf für Raw Samples wird zu 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 und auf Android, deviceType (watch, phone, chestStrap, usw.) ersetzen die DataSource-Objekte von Fit. Nutze sie, um Watch-Daten gegenüber Telefon-Daten zu bevorzugen, wenn beide vorhanden sind.

Schritt 6: Bucketed- und aggregierte Reads ersetzen

Fits bucketByTime sowie aggregate wird zu 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

Aggregiere Schritte immer, statt Raw Samples zu summieren. Health Connect dedupliziert überlappende Daten mehrerer Apps bei der Aggregation, und Rohsummen führen oft zu Doppelzählungen, wenn sowohl eine Watch als auch ein Telefon Schritte aufzeichnen.

Schritt 7: Die Sessions API ersetzen

Fit-Sessions werden auf Exercise-Sessions gemappt:

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

Anfrage workouts in einem read Berechtigungen zuerst. Das Plugin liest Workouts, schreibt aber keine Übungssitzungen. Wenn deine App Workouts aufzeichnet, schreibe die zugrunde liegenden Samples (Distanz, Kalorien, Herzfrequenz) und speichere die Sitzung selbst in deinem Backend, oder füge eine native Methode hinzu für ExerciseSessionRecord.

Schritt 8: Inserts ersetzen

Fits insertData wird zu 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(),
});

Werte müssen die Standard-Einheit jedes Typs verwenden (Kilogramm, Meter, Kilokalorien, bpm). Die metadata Option wird von Health Connect ignoriert.

Schritt 9: Google Play Review bestehen

Health-Berechtigungen lösen eine zusätzliche Prüfung aus:

1. Öffne in der Play Console App-Inhalte und füllen das aus Gesundheits-Apps Deklaration und das Health-Connect-Berechtigungsformular. Begründe jede angeforderte Berechtigung.
2. Stelle sicher, dass die in der Play Console verlinkte Datenschutzerklärung und die im Health-Connect-Sheet angezeigte Erklärung die Nutzung von Gesundheitsdaten beschreiben.
3. Aktualisiere die Datensicherheit Form: Gesundheits- und Fitnessdaten, gesammelt oder nicht, geteilt oder nicht.
4. Reiche einen Build ein, der nur die gerechtfertigten Berechtigungen deklariert. Zusätzlich deklarierte Berechtigungen sind der häufigste Ablehnungsgrund.

Plane ein, dass der Review länger dauert als bei einem normalen Update. Veröffentliche die Migration als eigenes Release, nicht vermischt mit unrelated Features.

Schritt 10: Nutzererwartungen anpassen

• Informiere die Nutzer, dass ihr Verlauf nun über Health Connect läuft und ältere Daten möglicherweise auf 30 Tage begrenzt sind, bis sie den Zugriff auf den Verlauf gewähren.
• Falls deine App Google Fit für den Cloud-Sync genutzt hat, verlagere diese Aufgabe jetzt auf dein Backend.
• Entferne „Connect Google Fit“-Buttons und benenne sie auf Android in „Connect Health Connect“ und auf iOS in „Connect Apple Health“ um.

Fehlerbehebung

isAvailable() gibt auf Android 13 false zurück: Health Connect ist nicht installiert oder veraltet. Rufe openHealthConnectSettings().

Das Permission-Sheet erscheint nie: Die Berechtigung ist im gemergten Manifest nicht deklariert oder wurde von dir entfernt mit tools:node="remove". Prüfe android/app/build/intermediates/merged_manifests.

Reads liefern nur 30 Tage: Anfrage requestHistoryAccess: true und deklarieren READ_HEALTH_DATA_HISTORY.

Schrittsummen sind höher als bei Google Fit: Du hast Rohdaten summiert. Verwende queryAggregated.

Leere Ergebnisse auf iOS: Entweder keine Daten oder Leseberechtigung verweigert. HealthKit gibt nicht an, welches der Fall ist.

Play Console lehnt das Update ab: Entferne nicht deklarierte oder nicht gerechtfertigte Health Connect-Berechtigungen und reiche mit klarer Begründung erneut ein.

Die Migration schrittweise ausrollen

Der native Teil (Plugin, Manifest, HealthKit-Fähigkeit) benötigt einen Store-Release. Danach sind Abfragen, UI und Datenmapping JavaScript, das du mit Capgo Live Updates iterieren kannst, während Nutzer den neuen Flow testen. Wenn du auch Live-Sensordaten liest, siehe unseren Guide zu Einen Herzfrequenzmonitor mit Capacitor bauen, und die Health-Plugin-Doku für jeden Datentyp.