Health Connect wird in Android 14 als gemeinsame Datenspeicherebene für Gesundheitsdaten von Nutzern bereitgestellt. Sie ist durch detaillierte Berechtigungen geschützt und kann als Android-System-App aufgerufen werden (in diesem Dokument als „Framework“-Modul bezeichnet).
Entwickler sollten das Health Connect-APK (Android 13) als Abwärtskompatibilitätsschicht für das Framework-Modell betrachten. Das Framework-Modell behält eine 100-prozentige Funktionsparität mit seinem APK-Vorgänger bei.
Während der Umstellung von Android 13 auf Android 14 ist es äußerst wichtig, dass die Nutzerfreundlichkeit so reibungslos und intuitiv wie möglich bleibt.
In diesem Dokument wird der Migrationsplan beschrieben, es werden einige Beispielmigrationsszenarien aufgeführt und Änderungen am Jetpack SDK aufgelistet, die den Zugriff auf die Health Connect API erleichtern.
Migrationsplan
- Nach der Veröffentlichung von Android 14 stellt Google Health Connect als Android-System-App bereit.
- Sobald die Funktionsparität erreicht ist, werden die Daten aus dem APK nachgetragen.
- Alle Einstiegspunkte sind auf die Benutzeroberfläche der System-App ausgerichtet.
- Die Datenmigration beginnt. Während der Migration werden die Modul-APIs mit dem Status „Migration wird ausgeführt“ angehalten. Dieser Status wird auch in der Health Connect-Benutzeroberfläche angezeigt.
- Sobald die Migration abgeschlossen ist, kann das APK deinstalliert werden.
Beispielszenarien für die Migration
Hier sind einige Beispielszenarien, die den Migrationsprozess sowohl für den Datentyp interval
als auch für den Datentyp series
erläutern:
Beispiel 1: Laufen (Intervalldaten)
Ein Nutzer hat 10 Jahre lang jeden Tag eine Stunde lang Laufdaten erfasst. Das entspricht:
- Datensätze für Trainingseinheiten: 365 * 10 * 1
- Schritte: 365 * 10 * 1
- Kalorien: 365 × 10 × 1
- Gesamt: 365 × 10 × 3 (365 × 30) = 10.150
Da ein Chunk 3.000 Einträge entspricht, ergeben die oben genannten Daten insgesamt etwa 4 Chunks.
Unsere internen Tests haben gezeigt, dass das Einfügen eines typischen Chunks etwa eine Sekunde dauert. Die oben genannten Daten würden also in etwa 4 Sekunden migriert.
Beispiel 2: Herzfrequenz (Seriendaten)
Ein Nutzer hat 5 Jahre lang Herzfrequenzdaten erfasst (jeweils ein Datensatz pro Minute), insgesamt 2.628.000 Datensätze.
Bei 3.000 Einträgen pro Block werden die Daten auf 876 Blöcke verteilt. Da das Einfügen eines Chunks etwa eine Sekunde dauert, werden die Daten in weniger als 15 Minuten migriert.
Vorgeschlagene Migrationsabfolge
Wir haben uns für eine sofortige Migration entschieden. In der Praxis bedeutet das, dass das APK inaktiv wird, sobald das Gerät auf Android 14 umgestellt wird, und dass dafür nur minimale Nutzereingriffe erforderlich sind.
Sehen wir uns den Migrationsablauf im Überblick an:
- Der Nutzer führt ein Upgrade auf Android 14 durch.
- Jetpack 14 leitet den Nutzer an die Modul-APIs weiter und blockiert ihn, während die Migration läuft.
- Der Migrationsprozess beginnt, wenn die Modulversion funktional mit dem APK kompatibel ist, d.h., die Modulversion enthält mindestens dieselben Funktionen. Sobald der Migrationsprozess gestartet wurde, migriert das APK Berechtigungen und Daten.
- Wenn beide Versionen nicht funktional kompatibel sind, muss die Modulversion aktualisiert werden. Sobald das Upgrade abgeschlossen ist, beginnt der Migrationsprozess.
- Sobald die Migration abgeschlossen ist, wird der Status in „Migration abgeschlossen“ geändert und die Blockierung der Modul-APIs aufgehoben.
- Das APK kann jetzt deinstalliert werden.
UI-Elemente für die Migration
Die folgenden Bildschirme werden vom Framework-Modul sowohl vor als auch während der Migration zu Bildungszwecken angezeigt:
Abbildung 1: Wenn das Health Connect-APK nicht für die Migration geeignet ist, wird eine Aufforderung angezeigt, in der der Nutzer aufgefordert wird, das APK zu aktualisieren. Wenn der Nutzer das Update ablehnt, funktioniert das Modul weiter und es werden Berechtigungen und Daten erfasst:
Abbildung 2. Wenn das Framework-Modul aktualisiert werden muss, damit es funktionsfähig ist, wird der Nutzer aufgefordert, das Update durchzuführen und sein Gerät neu zu starten. Wenn der Nutzer das Update ablehnt, funktioniert das Modul weiter und es werden Berechtigungen und Daten erfasst:
Abbildung 3 Während der Migration wird ein rotierendes Ladesymbol mit einem Text angezeigt, der erklärt, dass die Daten synchronisiert werden:
Deduplizierte Daten
Wenn das Framework-Modul mit dem Abrufen von Daten und Berechtigungen begonnen hat, bevor eine Migration oder cloudbasierte Wiederherstellung stattgefunden hat, gelten die folgenden Regeln.
Berechtigungen
Wenn Berechtigungen im Framework-Modul vorhanden sind, werden alle doppelten Berechtigungen, die aus dem APK stammen, während der Migration ignoriert.
Daten
Während der Migration werden doppelte Daten aus dem APK ignoriert. Jüngere Daten aus dem Modul haben Vorrang.
Die Daten werden am clientRecordId
dedupliziert, wenn die Datensatz-ID vom Kunden angegeben wird. Andernfalls werden Zeitintervalle (startTime
und endTime
für interne Einträge und time
für Instant-Einträge) zusammen mit dem Datentyp und dem Paketnamen der App als Schlüssel behandelt.
Änderungen am Jetpack SDK
Das Jetpack SDK dient als gemeinsamer Integrationspunkt sowohl für das Health Connect-APK als auch für die Health Connect-Framework-APIs.
OEMs können mit der Einbindung in Jetpack 13 beginnen, damit Sie die neue Bibliothek übernehmen und in Android 14 kompilieren können, sobald Jetpack 14 verfügbar ist.
Wir veröffentlichen eine neue Version des SDKs, die die Umstellung auf Android 14 unterstützt. Sie müssen einige Änderungen an Ihrer vorhandenen Integration vornehmen, um einen reibungslosen Übergang zu ermöglichen.
Erklärung zu Berechtigungen
Unter Android 13 deklarieren Sie Berechtigungen in einer Ressourcendatei, die mit dem Manifest verknüpft ist, in einem benutzerdefinierten Berechtigungsformat:
#AndroidManifest.xml
<activity>
android:name=".RationaleActivity"
android:exported="true">
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
</intent-filter>
<meta-data
android:name="health_permissions"
android:resource="@array/health_permissions"/>
</activity>
<queries>
<package android:name="com.google.android.apps.healthdata" />
</queries>
#health_permissions.xml
<resources>
<array name="health_permissions">
<item>androidx.health.permission.SleepSession.READ</item>
<item>androidx.health.permission.SleepStage.READ</item>
<item>androidx.health.permission.Weight.READ</item>
<item>androidx.health.permission.Weight.WRITE</item>
</array>
</resources>
Um Android 14 zu unterstützen, müssen Entwickler zum Standardformat für Berechtigungen wechseln:
#AndroidManifest.xml
<uses-permission android:name=”android.permission.health.READ_SLEEP” />
<uses-permission android:name=”android.permission.health.READ_WEIGHT” />
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT” />
<activity>
android:name=".RationaleActivity"
android:exported="true">
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>
</activity>
<queries>
<package android:name="com.google.android.apps.healthdata"/>
</queries>
Health Connect öffnen
Die meisten Drittanbieter-Apps haben eine Schaltfläche, über die die Health Connect App geöffnet wird, z. B. die Schaltfläche „Zugriff verwalten“ in Fitbit.
Unter Android 13 können Sie die Health Connect App entweder über den Paketnamen oder über die Aktion androidx.health.ACTION_HEALTH_CONNECT_SETTINGS
öffnen.
Unter Android 14 müssen Sie eine Intent-Aktion verwenden, die im Jetpack SDK angegeben ist. Diese hat je nach Android-Version unterschiedliche Werte:
@get:JvmName("getHealthConnectSettingsAction")
@JvmStatic val
ACTION_HEALTH_CONNECT_SETTINGS
Health Connect-Client herunterladen
Wir haben eine einzelne API namens sdkStatus
entwickelt, die in Jetpack 11 verfügbar ist und zwei andere eingestellte APIs ersetzt: IsSdkSupported()
und isProviderAvailable()
.
Änderungen an der API für Sitzungsaufzeichnungen
Im Rahmen der Alpha 10-Version wurden vier ExerciseSession
-Untertypen gelöscht:
ExerciseEvent
ExerciseLaps
ExerciseRepetitions
SwimmingStrokes
Wie bei ExerciseSessionRecord
wird SleepStage
zu einem Untertyp von SleepSession
.
Sowohl die ExerciseSessionRecord
-Untertypen als auch die SleepSession
-Änderungen werden im Rahmen des April-SDK-Updates veröffentlicht.
Aktualisierung des Trainingssitzungstyps
Die folgenden Trainingseinheiten werden nicht mehr unterstützt, sondern zu einem späteren Zeitpunkt als Segmenttypen hinzugefügt:
EXERCISE_TYPE_BACK_EXTENSION
EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
EXERCISE_TYPE_BENCH_PRESS
EXERCISE_TYPE_BENCH_SIT_UP
EXERCISE_TYPE_BURPEE
EXERCISE_TYPE_CRUNCH
EXERCISE_TYPE_DEADLIFT
EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
EXERCISE_TYPE_FORWARD_TWIST
EXERCISE_TYPE_JUMPING_JACK
EXERCISE_TYPE_JUMP_ROPE
EXERCISE_TYPE_LAT_PULL_DOWN
EXERCISE_TYPE_LUNGE
EXERCISE_TYPE_PLANK
EXERCISE_TYPE_SQUAT
EXERCISE_TYPE_UPPER_TWIST
Ersatztypen:
EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
EXERCISE_TYPE_STRENGTH_TRAINING
EXERCISE_TYPE_CALISTHENICS
Umgang mit Änderungsprotokollen
Änderungsprotokolle werden im Rahmen der Umstellung von APK auf Android 14 nicht migriert.
Nach Abschluss der Migration erhalten Sie TOKEN_EXPIRED
- oder TOKEN_INVALID
-Ausnahmen. Sie sollten in der folgenden Reihenfolge behandelt werden:
1. Alle Daten seit dem Zeitstempel „Zuletzt gelesen“ oder für die letzten 30 Tage lesen und duplizierte Daten entfernen
Speichert einen Zeitstempel dazu, wann eine App zuletzt Daten aus Health Connect gelesen hat. Nach Ablauf des Tokens sollten die Daten entweder aus diesem Wert oder aus den letzten 30 Tagen (je nachdem, was niedriger ist) noch einmal gelesen und mithilfe der UUID mit zuvor gelesenen Daten abgeglichen werden.
2. Daten seit dem Zeitstempel „Letztes Lesen“ lesen
Erstellen Sie einen Zeitstempel, der angibt, wann Daten zuletzt aus Health Connect gelesen wurden. Lesen Sie nach Ablauf des Tokens alle Daten nach diesem Wert.
3. Daten der letzten 30 Tage löschen und noch einmal lesen
Alle Daten löschen, die in den letzten 30 Tagen aus Health Connect gelesen wurden, und alle diese Daten noch einmal lesen (z. B. wie bei der Erstintegration von Apps in Health Connect)
4. Nichts tun (d.h. Daten der letzten 30 Tage noch einmal lesen und keine Duplikate entfernen)
Diese Option sollte nur als letztes Mittel verwendet werden. Es besteht das Risiko, dass doppelte Daten angezeigt werden. Entwickler sollten stattdessen die Optionen 1–3 in Betracht ziehen, da UUIDs bereits vorhanden sein sollten.
Android 14 APIs mit dem Jetpack SDK testen
Das Jetpack SDK für Android 14 wird am 7. Juni 2023 zusammen mit der Beta 3-Version von Android 14 veröffentlicht. Sie müssen Ihre App für Android 14 kompilieren, um das Jetpack SDK für Android 14 verwenden zu können.
Wenn Sie Ihre Lösung vor dem 7. Juni mit den Android Developer Preview-Builds testen möchten, wenden Sie sich bitte an Ihren Google-POC.
Wenn Sie Ihre Lösung mit der Beta 3-Version testen möchten, sollten Sie die folgenden Änderungen an Ihrem APK vornehmen:
- Legen Sie
compileSDKPreview = UpsideDownCake
fest. - Fügen Sie dem Manifest eine Intent für Android 14 hinzu:
# AndroidManifest.xml
<uses-permission android:name=”android.permission.health.READ_SLEEP”/>
<uses-permission android:name=”android.permission.health.READ_WEIGHT”/>
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT”/>
<activity>
android:name=".RationaleActivity"
android:exported="true">
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
</intent-filter>
</activity>
<activity-alias>
android:name="AndroidURationaleActivity"
android:exported="true"
android:targetActivity=".RationaleActivity"
android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
<intent-filter>
<action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
<category android:name="android.intent.category.HEALTH_PERMISSIONS" />
</intent-filter>
</activity-alias>
<queries>
<package android:name="com.google.android.apps.healthdata" />
</queries>
OEM-Anpassung
Unter Android 14 finden Sie die Einstellungen für den Datenschutz und die Datenverwaltung von Health Connect in den Systemeinstellungen.
Damit die Bildschirme für die Datenverwaltung und Berechtigungen wie ein Teil des Geräts aussehen, bietet Health Connect OEM-Designs mit benutzerdefinierten Overlays.
Eine Dokumentation zum OEM-Styling finden Sie in der Google Mobile Services-Dokumentation für Health Connect. Möglicherweise müssen Sie sich in Google Developers anmelden, um die Seite aufzurufen.