Google Fit zu Health Connect Migration in Capacitor

Die Migration von Google Fit zu Health Connect bedeutet, dass Sie jeden Fit-API-Aufruf in Ihrer Capacitor-Anwendung durch Health Connect auf Android und durch HealthKit auf iOS ersetzen, wenn Sie dort auch liefern. Google hat am 1. Mai 2024 neue Fit-Anmeldungen eingestellt und unterstützt die Fit-APIs nur bis Ende 2026. Diese Anleitung abbildet Fit-Datentypen und -Aufrufe auf Health Connect, zeigt den Ersatz-code und deckt die Play-Console-Bewertung ab, die mit Gesundheitsberechtigungen kommt. @capgo/capacitor-health, und umfasst die Überprüfung im Google Play Console, die mit Genehmigungen für Gesundheitsdaten einhergeht.

Google Fit Abschaffungstabelle

Google's Migration-Hinweise sagen, dass es keine Alternative zur Fit-REST API mit der gleichen Form gibt: On-Device-Anwendungen wechseln zu Health Connect, und Cloud-Integrationen wechseln zur account-basierten Google Health API. Wenn Sie ein genaues Abschaltdatum irgendwo zitieren, überprüfen Sie es gegen Google's eigene FAQ, bevor Sie sich darum planen

Welche Änderungen treten auf, wenn Sie zu Health Connect wechseln

Die größte Produktänderung ist das Gerätezentrierte Modell. Health Connect-Daten auf einem Telefon sind nicht auf einem anderen sichtbar. Wenn Ihre App eine Historie über Geräte anzeigt, synchronisieren Sie die Lesungen mit Ihrem eigenen Backend.

Fit-Datentypen auf Health Connect abbilden

Fits ohne direkten Äquivalent

• Play Console Health Connect-Erklärung (com.google.heart_minutesund Bewegungsminuten (com.google.active_minutes) waren Google Fit-Werte. Health Connect speichert Rohdaten, nicht diese Werte. Berechnen Sie Ihre eigene Metrik aus Herzfrequenz und Trainings-Sessions.
• Aktivitätsproben mit pro-sekundären Aktivitärtypen werden durch Trainingsessions mit Abschnitten ersetzt.
• Standortproben innerhalb von Trainings werden zu ExerciseRoute Datensätze in Health Connect, die eine separate Berechtigung benötigen und nicht durch den Plugin-Typen angezeigt werden.
• Schrittfrequenz, Geschwindigkeit und Leistung existieren in Health Connect (StepsCadenceRecord, SpeedRecord, PowerRecord) aber werden nicht durch die Plugin-Typen abgedeckt. Wenn Sie auf sie angewiesen sind, ist eine kleine benutzerdefinierte native Methode der schnellste Weg.

Überprüfen Sie, bevor Sie schreiben code: Listen Sie alle DataType und jede API du anrufst (History, Aufzeichnung, Sitzungen, Sensoren, Konfiguration, REST), und kennzeichne jede als zugeordnet, neu berechnet oder abgeworfen.

Schritt 1: Entfernen Sie Google Fit

Entfernen Sie die Fit-Integration aus Ihrem Android-Projekt und JavaScript:

• Entfernen com.google.android.gms:play-services-fitness und, wenn nur für Fit verwendet wird play-services-auth von build.gradle.
• Entfernen Sie den Fit-OAuth-Kunden von Google Cloud und die Fitnessberechtigungen von Ihrem Zustimmungsbildschirm.
• Entfernen Sie die alte Community-Plugin für Google Fit Capacitor, dann starten Sie bunx cap sync.

Halten Sie die Fit-code in einem Zweig, bis die neue Version live ist, damit Sie historische Daten exportieren können, wenn Benutzer danach fragen.

Step 2: Install the health plugin

bun add @capgo/capacitor-health
bunx cap sync

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

Android-Einrichtung

Der Plugin kombiniert die Health Connect-Lese- und Schreibrechte für seine unterstützten Typen in Ihrem Manifest, plus die <queries> Eintrag für das Health Connect-Paket und die Begründung für die Berechtigungstätigkeit. Sie müssen:

1. Eine Datenschutzrichtlinie bereitstellen. Health Connect öffnet sie von der Berechtigungstabelle. Entweder fügen Sie android/app/src/main/assets/public/privacypolicy.html, oder setzen Sie eine URL in android/app/src/main/res/values/strings.xml:

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

2. Die Berechtigungen einschränken. Google Play überprüft jede Health Connect-Berechtigung, die Sie deklarieren. Wenn Sie nur Schritte und Herzfrequenz lesen, entfernen Sie den Rest mit tools:node="remove":

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

3. Add history access if you need it. Health Connect beschränkt die Lesen auf etwa die letzten 30 Tage, es sei denn, der Benutzer erteilt READ_HEALTH_DATA_HISTORY:

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

iOS-Einrichtung

Die HealthKit-Fähigkeit in Xcode aktivieren und Benutzungsstrings hinzufügen zu 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 überprüfen

Google Fit funktionierte überall, wo Play-Dienste existierten. Health Connect könnte auf Android 13 und älter fehlen oder eine Aktualisierung benötigen.

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

Eine kurze Erklärung anzeigen, bevor Sie weiterleiten. Benutzer, die von Health Connect noch nie gehört haben, sind verwirrt, wenn der Play Store ohne Vorwarnung geöffnet wird.

Schritt 4: Ersetze OAuth durch Berechtigungen

Die Fit-Fluss war: Google-Anmeldung, Anfrage von Fitnessberechtigungen, dann Aufruf von APIs. Der neue Fluss ist ein einzelner Berechtigungsbildschirm:

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 sind pro Datentyp und der Benutzer kann jede Teilmenge gewähren. Verwende checkAuthorization mit denselben Optionen bei jedem App-Start, da Benutzer den Zugriff in den Health Connect-Einstellungen jederzeit widerrufen können. Auf iOS versteckt HealthKit Leseverbote für Datenschutz, daher kann ein leerer Ergebnisbedeutet „keine Daten“ oder „keinen Zugriff“.

Schritt 5: Ersetze Historie API-Lesevorgänge

Ein Fit- readData Anruf für Rohproben 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, chestStrapund so weiter, ersetze Fit’s Datenquelleobjekte. Verwende sie, um Daten von der Uhr vor Daten vom Smartphone zu bevorzugen, wenn beide existieren.

Schritt 6: Ersetze gruppierte und aggregierte Lesevorgänge

Schritts bucketByTime plus aggregate wird 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

Ziehen Sie stattdessen Schritte zusammen, anstatt Rohdaten zu summieren. Health Connect entfernt überlappende Daten aus mehreren Apps während der Aggregation und Rohsummen zählen oft doppelt, wenn ein Armband und ein Smartphone Schritte aufzeichnen.

Schritt 7: Ersetzen Sie die Sitzungen API

Schrittsitzungen entsprechen Übungssitzungen:

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 read erst die Berechtigungen. Der Plugin liest Workouts, schreibt aber keine Übungssitzungen, daher müssen Sie, wenn Ihr App Workouts aufzeichnet, die zugrunde liegenden Proben (Distanz, Kalorien, Herzfrequenz) und die Sitzung selbst in Ihrem Backend speichern oder eine native Methode für ExerciseSessionRecord.

Schritt 8: Ersetzen Sie Einfügungen

Schritts insertData wird 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 Standardeinheit jeder Art verwenden (Kilogramm, Meter, Kilokalorie, bpm). Die metadata Option wird von Health Connect ignoriert.

Schritt 9: Google Play-Bewertung abschließen

Health permissions trigger extra review:

1. Zugriffsrechte auf Gesundheitsdaten lösen zusätzliche Überprüfung aus: Inhalte der App Angebotsinhalt und füllen Sie die Erlaubnis und die Health Connect-Berechtigungsform. Rechtfertigen Sie jede erbetene Erlaubnis.
2. Stellen Sie sicher, dass die Datenschutzrichtlinie im Google Play Console und die im Health Connect-Blatt angezeigte Beschreibung die Verwendung von Gesundheitsdaten beschreiben.
3. Aktualisieren Sie Daten-Sicherheit form: Gesundheits- und Fitnessdaten, gesammelt oder nicht, geteilt oder nicht.
4. Ein Build einreichen, der nur die Rechte deklariert, die Sie gerechtfertigt haben. Überflüssig deklarierte Rechte sind die häufigste Ablehnung.

Planen Sie eine Überprüfung, die länger dauert als ein normaler Update. Verschicken Sie die Migration als eigenes Release, nicht mit unabhängigen Funktionen vermengt.

Schritt 10: Migrationserwartungen der Benutzer

• Ihre Historie wird nun von Health Connect bereitgestellt, ältere Daten sind jedoch auf 30 Tage limitiert, bis Sie die Historie-Zugriffsrechte erteilen.
• Wenn Ihr App Fit als Cloud-Synchronisation verwendet hat, übernehmen Sie diese Verantwortung jetzt in Ihrem Backend.
• Entferne die Schaltflächen „Google Fit verbinden“ und benenne sie auf Android als „Gesundheitsverbindung verbinden“ und auf iOS als „Apple Gesundheitsverbindung“.

Troubleshooting

isAvailable() false auf Android 13Health Connect ist nicht installiert oder veraltet. Aufrufen Sie openHealthConnectSettings().

Die Berechtigungsliste erscheint nieDie Berechtigung ist nicht im kombinierten Manifest deklariert oder Sie haben sie mit tools:node="remove". Überprüfen android/app/build/intermediates/merged_manifests.

Nur 30 Tage zurückliegende Daten werden geliefert: Anfrage requestHistoryAccess: true und deklarieren READ_HEALTH_DATA_HISTORY.

Schrittzahlen sind höher als bei Google FitBerechnen Sie die Summe der Rohdaten. Verwenden Sie queryAggregated.

Leere Ergebnisse auf iOS: Entweder gibt es keine Daten oder die Leseberechtigung wurde abgelehnt. HealthKit sagt Ihnen nicht, welches ist.

Play Console lehnt die Aktualisierung abEntfernen Sie unerklärte oder ungerechtfertigte Health Connect-Berechtigungen und stellen Sie sie mit einer klaren Begründung erneut ein.

Verschicken Sie die Migration in Etappen

Die native Komponente (Plugin, Manifest, HealthKit-Fähigkeit) benötigt eine Store-Veröffentlichung. Anschließend sind Queries, UI und Datenmapping JavaScript, was Sie mit iterativen Schritten bearbeiten können. Capgo Live-Updates Während die Benutzer den neuen Workflow testen. Wenn Sie auch Live-Sensordaten lesen, sehen Sie sich unsere Anleitung zum Ein Herzfrequenzmesser bauen mit Capacitor, und das Gesundheits-Plugin-Dokumentation Plugin-Dokumentation für jeden Datentyp.