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

Health Connect wird mit Android 14 als gemeinsame Datenspeicherebene für Gesundheits- und Fitnessdaten von Verbrauchern ausgeliefert. Die Daten sind durch detaillierte Berechtigungen geschützt und als Android-System-App zugänglich (in diesem Dokument als „Framework“-Modul bezeichnet).

Entwickler sollten das Health Connect-APK (Android 13) als Abwärtskompatibilitätsebene für das Framework-Modell betrachten. Das Framework-Modell behält die volle Funktionsparität mit seinem APK-Vorgänger bei.

Während der Umstellung von Android 13 auf Android 14 ist es von entscheidender Bedeutung, dass die Nutzererfahrung so reibungslos und intuitiv wie möglich bleibt.

In diesem Dokument wird der Migrationsplan beschrieben. Außerdem werden einige Beispielmigrationsszenarien und Änderungen am Jetpack SDK aufgeführt, das den Zugriff auf die Health Connect API erleichtert.

Migrationsplan

  1. Sobald Android 14 veröffentlicht wird, wird Health Connect von Google als Android-System-App bereitgestellt.
  2. Sobald die Funktionen gleichwertig sind, werden die Daten aus dem APK nachgetragen.
  3. Alle Einstiegspunkte sind auf die Benutzeroberfläche der System-App ausgerichtet.
  4. Die Datenmigration wird gestartet. Während der Migration werden die Modul-APIs mit dem Status „Migration wird ausgeführt“ angehalten. Diese Informationen sind auch in der Health Connect-Benutzeroberfläche sichtbar.
  5. Nach Abschluss der Migration kann das APK deinstalliert werden.

Beispielszenarien für die Migration

Hier sind einige Beispielszenarien, die den Migrationsprozess für die Datentypen interval und series erläutern:

Beispiel 1: Laufen (Intervall-Daten)

Ein Nutzer hat 10 Jahre lang jeden Tag eine Stunde lang Laufdaten aufgezeichnet. Das entspricht:

  • Trainingssitzungsaufzeichnungen: 365 * 10 * 1
  • Schritte: 365 × 10 × 1
  • Kalorien: 365 × 10 × 1
  • Gesamt: 365 × 10 × 3 = 10.950

Da ein Chunk 3.000 Datensätzen entspricht, sind das insgesamt etwa vier Chunks.

Unsere internen Tests haben ergeben, dass das Einfügen eines typischen Chunks etwa eine Sekunde dauert. Die Daten im Beispiel würden also in etwa vier Sekunden migriert.

Beispiel 2: Herzfrequenz (Seriendaten)

Ein Nutzer hat über 5 Jahre hinweg Herzfrequenzdaten gesammelt (mit einem Datensatz pro Minute), was insgesamt 2.628.000 Datensätzen entspricht.

Bei 3.000 Datensätzen pro Chunk werden die Daten auf 876 Chunks verteilt. Da das Einfügen eines Chunks etwa eine Sekunde dauert, würden die Daten in weniger als 15 Minuten migriert.

Vorgeschlagener Migrationsablauf

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 aktualisiert wird. Dazu ist nur ein minimaler Nutzereingriff erforderlich.

Allgemeiner Migrationsablauf:

  1. Der Nutzer führt ein Upgrade seines Geräts auf Android 14 durch.
  2. Jetpack 14 leitet den Nutzer zu den Modul-APIs weiter und blockiert ihn, während die Migration läuft.
  3. Die Migration beginnt, wenn die Modulversion funktionskompatibel mit dem APK ist. Das bedeutet, dass die Modulversion dieselben oder mehr Funktionen enthält. Sobald die Migration begonnen hat, werden Berechtigungen und Daten des APK migriert.
    1. Wenn beide Versionen nicht funktionskompatibel sind, muss die Modulversion aktualisiert werden. Nach Abschluss des Upgrades beginnt der Migrationsprozess.
  4. Nach Abschluss der Migration ändert sich der Status zu „Migration abgeschlossen“ und die Modul-APIs werden entsperrt.
  5. Die APK kann jetzt deinstalliert werden.

UI-Elemente für die Migration

Die folgenden Bildschirme werden vom Framework-Modul zu Informationszwecken für Nutzer sowohl vor als auch während der Migration angezeigt:

Abbildung 1: Wenn das Health Connect-APK nicht für die Migration vorbereitet ist, wird eine Aufforderung angezeigt, in der der Nutzer aufgefordert wird, das APK zu aktualisieren. Wenn der Nutzer das Update ablehnt, funktioniert das Modul weiterhin und es werden Berechtigungen und Daten gesammelt.

Abbildung von „Smartphone-Update erforderlich“
Abbildung 1: Aufforderung zum Aktualisieren der Health Connect-APK.

Abbildung 2: Wenn für das Framework-Modul ein Update erforderlich ist, damit es mit der Funktion kompatibel ist, wird eine Aufforderung angezeigt, in der der Nutzer gebeten wird, das Update durchzuführen und sein Gerät neu zu starten. Wenn der Nutzer das Update ablehnt, funktioniert das Modul weiterhin und es werden Berechtigungen und Daten gesammelt.

Abbildung: APK-Update erforderlich
Abbildung 2: Aufforderung zum Aktualisieren des Framework-Moduls.

Abbildung 3: Während der Migration wird ein rotierendes Ladesymbol mit einem Text angezeigt, der darauf hinweist, dass Daten synchronisiert werden.

Abbildung zur Datensynchronisierung
Abbildung 3: Datenmigration läuft.

Deduplizierte Daten

Wenn das Framework-Modul vor einer Migration oder cloudbasierten Wiederherstellung mit der Erfassung von Daten und Berechtigungen begonnen 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. Neuere Daten aus dem Modul werden bevorzugt.

Die Daten werden auf clientRecordId dedupliziert, wenn die Datensatz-ID vom Client bereitgestellt wird. Andernfalls werden Zeitintervalle (startTime und endTime für interne Datensätze und time für Sofortdatensätze) zusammen mit dem Datentyp und dem Paketnamen der App als Schlüssel behandelt.

Änderungen im Jetpack SDK

Das Jetpack SDK dient als gemeinsamer Integrationspunkt für das Health Connect APK und die Health Connect-Framework-APIs.

OEMs können mit der Integration von Jetpack 13 beginnen, damit sie die neue Bibliothek nutzen und in Android 14 kompilieren können, wenn Jetpack 14 verfügbar ist.

Wir werden eine neue Version des SDK veröffentlichen, die die Umstellung auf Android 14 unterstützt. Sie müssen einige Änderungen an Ihrer bestehenden Integration vornehmen, um einen reibungslosen Übergang zu gewährleisten.

Erklärung zu Berechtigungen

In Android 13 deklarieren Sie Berechtigungen in einer Ressourcendatei, die mit dem Manifest verknüpft ist, mit 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, mit der 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.

In Android 14 müssen Sie eine Intent-Aktion verwenden, die im Jetpack SDK angegeben ist und je nach Android-Version, auf die sie sich bezieht, unterschiedliche Werte hat:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

Health Connect-Client abrufen

Wir haben eine einzelne API namens sdkStatus erstellt, die in Jetpack 11 verfügbar ist und zwei andere eingestellte APIs ersetzt: IsSdkSupported() und isProviderAvailable().

Änderungen an der Session Record API

Im Rahmen der Veröffentlichung von alpha10 wurden vier ExerciseSession-Untertypen gelöscht:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Wie bei ExerciseSessionRecord wird SleepStage ein Untertyp von SleepSession.

Sowohl die ExerciseSessionRecord-Untertypen als auch die SleepSession-Änderungen werden im Rahmen des SDK-Updates im April veröffentlicht.

Aktualisierung des Trainingssitzungstyps

Die folgenden Trainingseinheitstypen werden nicht mehr unterstützt und stattdessen 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 bei der Umstellung von APK auf Android 14 nicht migriert.

Nach Abschluss der Migration erhalten Sie TOKEN_EXPIRED- oder TOKEN_INVALID-Ausnahmen. Diese sollten auf folgende Weise behandelt werden (in der Reihenfolge der Präferenz):

1. Alle Daten seit dem Zeitstempel „Letzter Lesevorgang“ oder der letzten 30 Tage lesen und deduplizieren

Speichern eines Zeitstempels, wann eine App zuletzt Daten aus Health Connect gelesen hat. Wenn das Token abläuft, sollten die Daten entweder aus diesem Wert oder aus den vorherigen 30 Tagen (je nachdem, was dem Minimum entspricht) neu gelesen und anhand der UUID mit zuvor gelesenen Daten dedupliziert werden.

2. Daten seit dem Zeitstempel „Letzter Lesevorgang“ lesen

Legen Sie einen Zeitstempel fest, der angibt, wann Daten zuletzt aus Health Connect gelesen wurden, und lesen Sie nach Ablauf des Tokens alle Daten nach diesem Wert.

3. Daten der letzten 30 Tage löschen und neu lesen

Alle Daten, die in den letzten 30 Tagen aus Health Connect gelesen wurden, löschen und alle diese Daten noch einmal lesen (z.B. wie beim ersten Integrieren von Apps in Health Connect).

4. Nichts tun (d.h. Daten für die letzten 30 Tage noch einmal lesen und nicht deduplizieren)

Diese Option sollte nur als letztes Mittel verwendet werden, da das Risiko besteht, dass doppelte Daten angezeigt werden. Entwickler sollten stattdessen die Optionen 1 bis 3 in Betracht ziehen, da UUIDs bereits vorhanden sein sollten.

Android 14-APIs mit dem Jetpack SDK testen

Das Android 14 Jetpack SDK wird voraussichtlich 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 Android 14 Jetpack SDK 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 an Ihren Google-Ansprechpartner.

Wenn Sie Ihre Lösung mit Beta 3 testen möchten, sollten Sie die folgenden Änderungen an Ihrem APK vornehmen:

  1. Legen Sie compileSDKPreview = UpsideDownCake fest.
  2. Aktualisieren Sie das Manifest, um eine Intention für Android 14 einzufügen:
# 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

In Android 14 befinden sich die Health Connect-Einstellungen für Datenschutz und Datenverwaltung in den Systemeinstellungen.

Damit die Bildschirme für die Datenverwaltung und Berechtigungen wie ein Teil des Geräts aussehen, bietet Health Connect OEM-Theming durch die Verwendung benutzerdefinierter Overlays.

Die Dokumentation zum OEM-Styling finden Sie in der Dokumentation zu Health Connect Google Mobile Services. Möglicherweise müssen Sie sich in Google Developers anmelden, um die Seite aufrufen zu können.