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

Health Connect wird mit Android 14 als gemeinsame Datenspeicherebene für Gesundheitsdaten von Verbrauchern verpackt, durch detaillierte Berechtigungen geschützt und als Android-System-App zugänglich (im gesamten 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 100% gleiche Funktionen wie sein APK-Vorgänger.

Beim Wechsel von Android 13 auf 14 ist es von entscheidender Bedeutung, dass die Nutzererfahrung so reibungslos und intuitiv wie möglich bleibt.

In diesem Dokument wird der Migrationsplan beschrieben, einige Beispiele für Migrationsszenarien aufgeführt und Änderungen am Jetpack SDK aufgeführt, das den Zugriff auf die Health Connect API ermöglicht.

Migrationsplan

  1. Sobald Android 14 veröffentlicht wird, stellt Google Health Connect als Android-System-App zur Verfügung.
  2. Die Daten werden dann aus dem APK aufgefüllt, sobald die Funktionarität erreicht ist.
  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 in Bearbeitung“ ausgesetzt. Dies ist auch in der Health Connect-UI sichtbar.
  5. Nach Abschluss der Migration kann das APK deinstalliert werden.

Beispiele für Migrationsszenarien

Hier sind einige Beispielszenarien, in denen der Migrationsprozess für die Datentypen interval und series erläutert wird:

Beispiel 1: Wird ausgeführt (Intervalldaten)

Ein Benutzer hat täglich 10 Jahre Laufaufzeichnungen für 1 Stunde gesammelt. Dies entspricht:

  • Trainingsaufzeichnungen: 365 * 10 * 1
  • Schritte: 365 * 10 * 1
  • Kalorien: 365 * 10 * 1
  • Summe = 365 * 10 * 3 (365 * 30) = 10.150

Da ein Block 3.000 Datensätzen entspricht, ergeben sich aus den oben genannten Daten insgesamt etwa 4 Blöcke.

Unsere internen Tests haben bestätigt, dass das Einfügen eines Blocks normalerweise etwa eine Sekunde dauert. Die oben genannten Daten würden also in etwa 4 Sekunden migriert werden.

Beispiel 2 – Herzfrequenz (Seriendaten)

Ein Nutzer hat Herzfrequenzdaten für 5 Jahre erfasst (jede Minute wird ein Datensatz erstellt) und insgesamt 2.628.000 Datensätze.

Bei 3.000 Datensätzen pro Block werden die Daten auf 876 Blöcke verteilt. Da das Einfügen eines Blocks etwa eine Sekunde dauert, werden die Daten in weniger als 15 Minuten migriert.

Vorgeschlagener Migrationsablauf

Wir haben uns für die Sofortmigration entschieden. In der Praxis bedeutet dies, dass das APK mit minimalem Nutzereingriff deaktiviert wird, sobald das Gerät auf Android 14 aktualisiert wird.

Sehen wir uns einen allgemeinen Migrationsablauf genauer an:

  1. Der Nutzer führt ein Upgrade auf Android 14 durch.
  2. Jetpack 14 leitet den Nutzer zu den Modul-APIs weiter und blockiert sie während der Migration.
  3. Der Migrationsprozess beginnt, wenn die Modulversion mit dem APK kompatibel ist, d.h., die Modulversion enthält denselben Funktionsumfang oder mehr. Sobald der Migrationsprozess begonnen hat, migriert das APK die Berechtigungen und Daten.
    1. Wenn beide Versionen nicht funktionskompatibel sind, muss die Modulversion aktualisiert werden. Nach Abschluss des Upgrades beginnt der Migrationsprozess.
  4. Sobald die Migration abgeschlossen ist, ändert sich der Status in „Migration abgeschlossen“ und die Blockierung der Modul-APIs wird aufgehoben.
  5. Das APK kann jetzt deinstalliert werden.

UI-Elemente für die Migration

Die folgenden Bildschirme werden vom Framework-Modul zur Aufklärung der Nutzer angezeigt, sowohl vor als auch während der Migration:

Abbildung 1: Wenn das Health Connect-APK nicht auf die Migration beschränkt ist, wird eine Aufforderung angezeigt, in der der Nutzer aufgefordert wird, das APK zu aktualisieren. Wenn der Nutzer die Aktualisierung ablehnt, funktioniert das Modul weiterhin und sammelt Berechtigungen und Daten:

Smartphone-Update erforderlich


Abbildung 2: Wenn das Framework-Modul eine Aktualisierung benötigt, um es funktionskompatibel zu werden, wird eine Aufforderung angezeigt, in der der Nutzer aufgefordert wird, die Aktualisierung durchzuführen und sein Gerät neu zu starten. Wenn der Nutzer die Aktualisierung ablehnt, funktioniert das Modul weiterhin und beginnt, Berechtigungen und Daten zu erfassen:

APK-Update erforderlich


Abbildung 3: Während des Migrationsvorgangs wird ein rotierendes Ladesymbol mit dem Text angezeigt, der darauf hinweist, 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 im Framework-Modul Berechtigungen vorhanden sind, werden alle doppelten Berechtigungen, die vom APK übernommen wurden, während der Migration ignoriert.

Daten

Doppelte Daten aus dem APK werden während der Migration ignoriert. Aktuellere Daten aus dem Modul werden bevorzugt.

Die Daten werden am clientRecordId dedupliziert, wenn die Eintrags-ID vom Client bereitgestellt wird. Ist das nicht der Fall, werden die Zeitintervalle (startTime und endTime für interne Datensätze und time für Instant-Datensä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 Einbindung in Jetpack 13 beginnen. Wenn Jetpack 14 verfügbar ist, können Sie die neue Bibliothek übernehmen und innerhalb von Android 14 kompilieren.

Wir veröffentlichen eine neue SDK-Version, die die Umstellung auf Android 14 unterstützt. Für einen reibungslosen Übergang müssen Sie einige Änderungen an Ihrer bestehenden Integration vornehmen.

Erklärung zu Berechtigungen

In Android 13 werden Berechtigungen mithilfe eines Formats für benutzerdefinierte Berechtigungen in einer Ressourcendatei deklariert, die mit dem Manifest verknüpft ist:

#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>

Zur Unterstützung von Android 14 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 zum Öffnen der Health Connect-App, z. B. die Schaltfläche „Zugriff verwalten“ in Fitbit.

In Android 13 öffnest du die Health Connect-App entweder über den Paketnamen oder über die Aktion androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

In Android 14 musst du eine im Jetpack SDK angegebene Intent-Aktion verwenden, die je nach Android-Version, für die sie ausgeführt wird, unterschiedliche Werte hat:

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

Health Connect-Client abrufen

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

API-Änderungen für Sitzungseinträge

Im Rahmen der Alpha10-Version 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 Trainingsarten werden nicht mehr unterstützt und später 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

Ersatzarten:

  • 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 in der Reihenfolge ihrer Präferenz so gehandhabt werden:

1. Alle Daten seit dem Zeitstempel „Letzter Lesevorgang“ oder aus den letzten 30 Tagen lesen und deduplizieren

Speichert einen Zeitstempel, der angibt, wann eine App zuletzt Daten aus Health Connect gelesen hat. Nach Ablauf des Tokens sollten die Daten entweder noch einmal aus diesem Wert oder aus den vorherigen 30 Tagen (je nachdem, was dem Minimum entspricht) noch einmal gelesen und mit zuvor gelesenen Daten mithilfe der UUID dedupliziert werden.

2. Daten seit dem Zeitstempel „Zuletzt gelesen“ lesen

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

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

Alle in den letzten 30 Tagen aus Health Connect gelesenen Daten löschen und alle diese Daten noch einmal lesen (z.B. nach der ersten Einbindung von Apps in Health Connect).

4. Nichts tun (z.B. Daten der letzten 30 Tage noch einmal lesen und keine Duplikate entfernen)

Dies sollte nur als letztes Mittel verwendet werden, da es mit dem Risiko verbunden ist, dass doppelte Daten angezeigt werden. Entwickler sollten stattdessen die Optionen 1 bis 3 ausprobieren, da UUIDs bereits vorhanden sein sollten.

Android 14 APIs mit Jetpack SDK testen

Das Android 14 Jetpack SDK soll am 7. Juni 2023 zusammen mit der Betaversion 3 von Android 14 veröffentlicht werden. Du musst mit der Kompilierung deiner App für Android 14 beginnen, um das Android 14 Jetpack SDK verwenden zu können.

Wenn du deine Lösung vor dem 7. Juni anhand der Android-Entwicklervorschau-Builds testen möchtest, wende dich an deinen Google-POC.

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

  1. Legen Sie compileSDKPreview = UpsideDownCake fest.
  2. Aktualisieren Sie das Manifest so, dass es einen Intent für Android 14 enthält:
# 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

Bei Android 14 befinden sich die Datenschutz- und Datenverwaltungsfunktionen von Health Connect in den Systemeinstellungen.

Damit die Bildschirme für Datenverwaltung und Berechtigungen wie ein Teil des Geräts aussehen und sich anfühlen, bietet Health Connect OEM-Themen durch die Verwendung von benutzerdefinierten Overlays.

Informationen zu OEM-Stilen findest du in der Dokumentation zu den Google Mobile-Diensten von Health Connect.