Health Connect von Android 13 (APK) zu Android 14 (Framework) migrieren

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

  1. Nach der Veröffentlichung von Android 14 stellt Google Health Connect als Android-System-App bereit.
  2. Sobald die Funktionsparität erreicht ist, werden die Daten aus dem APK nachgetragen.
  3. Alle Einstiegspunkte sind auf die Benutzeroberfläche der System-App ausgerichtet.
  4. 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.
  5. 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:

  1. Der Nutzer führt ein Upgrade auf Android 14 durch.
  2. Jetpack 14 leitet den Nutzer an die Modul-APIs weiter und blockiert ihn, während die Migration läuft.
  3. 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.
    1. Wenn beide Versionen nicht funktional kompatibel sind, muss die Modulversion aktualisiert werden. Sobald das Upgrade abgeschlossen ist, beginnt der Migrationsprozess.
  4. Sobald die Migration abgeschlossen ist, wird der Status in „Migration abgeschlossen“ geändert und die Blockierung der Modul-APIs aufgehoben.
  5. 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:

Smartphone-Update erforderlich


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:

APK-Update erforderlich


Abbildung 3 Während der Migration wird ein rotierendes Ladesymbol mit einem Text angezeigt, der erklärt, dass die Daten synchronisiert werden:

Datensynchronisierung

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:

  1. Legen Sie compileSDKPreview = UpsideDownCake fest.
  2. 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.