Migrer Santé Connect d'Android 13 (APK) vers Android 14 (framework)

Santé Connect sera empaquetée avec Android 14 en tant que couche de stockage de données commune pour les données de santé grand public. Elle sera protégée par des autorisations précises, et accessible en tant qu'application système Android (appelée module de "framework" tout au long de ce document).

Les développeurs doivent considérer l'APK de Santé Connect (Android 13) comme une couche de rétrocompatibilité pour le modèle de framework. Le modèle de framework conserve une parité des fonctionnalités de 100 % avec son APK précédent.

Pendant la transition d'Android 13 vers la version 14, il est essentiel que l'expérience utilisateur reste aussi fluide et intuitive que possible.

Ce document décrit le plan de migration, fournit des exemples de scénarios de migration et indique les modifications apportées au SDK Jetpack, qui facilite l'accès à l'API Santé Connect.

Plan de migration

  1. Une fois qu'Android 14 sera publié, Google passera à Santé Connect en tant qu'application système Android.
  2. Les données seront ensuite remplies à partir de l'APK une fois la parité des fonctionnalités atteinte.
  3. Tous les points d'entrée cibleront l'interface utilisateur de l'application système.
  4. La migration des données commencera. Pendant la migration, les API des modules seront suspendues, et leur état indiquera que la migration est en cours. Cela sera également visible dans l'interface utilisateur de Santé Connect.
  5. Une fois la migration terminée, l'APK pourra être désinstallé.

Exemples de scénarios de migration

Voici quelques exemples illustrant le processus de migration pour les types de données interval et series :

Exemple 1 : Course à pied (données d'intervalle)

Depuis 10 ans, un utilisateur collecte des données de course à pied à raison d'une heure chaque jour. Cela revient à :

  • Enregistrements des séances d'entraînement : 365 * 10 * 1
  • Pas : 365 * 10 * 1
  • Calories : 365 * 10 * 1
  • Total = 365 * 10 * 3 (365 * 30) = 10 150

Étant donné qu'un segment équivaut à 3 000 enregistrements, les données ci-dessus totalisent environ 4 segments.

Nos tests internes ont confirmé que l'insertion d'un segment typique prenait environ une seconde. Les données ci-dessus devraient donc être migrées en quatre secondes environ.

Exemple 2 : Fréquence cardiaque (données séquentielles)

Depuis cinq ans, un utilisateur collecte des données sur la fréquence cardiaque (avec un enregistrement créé toutes les minutes) pour un total de 2 628 000 enregistrements.

Avec 3 000 enregistrements par segment, les données sont réparties sur 876 segments. L'insertion d'un segment prend environ une seconde. La migration des données devrait donc s'effectuer en moins de 15 minutes.

Processus de migration proposé

Nous avons décidé d'opter pour une migration instantanée. En pratique, cela signifie que l'APK deviendra inactif dès que l'appareil sera mis à niveau vers Android 14, avec une intervention minimale de l'utilisateur.

Passons en revue un processus de migration global :

  1. L'utilisateur passe à Android 14.
  2. Jetpack 14 achemine l'utilisateur vers les API du module et les bloque pendant la migration.
  3. Le processus de migration commence lorsque la version du module est compatible avec l'APK, c'est-à-dire lorsque la version du module contient au minimum le même ensemble de fonctionnalités. Une fois le processus de migration lancé, l'APK migre les autorisations et les données.
    1. Si les deux versions ne sont pas compatibles, vous devez mettre à niveau la version du module. Le processus de migration démarre une fois cette mise à niveau terminée.
  4. Une fois la migration terminée, son état indique que la migration est terminée, et les API du module sont débloquées.
  5. L'APK peut désormais être désinstallé.

Éléments de l'UI de migration

Les écrans suivants sont affichés par le module de framework à des fins pédagogiques, avant et pendant la migration :

Figure 1 : Si l'APK de Santé Connect n'est pas "compatible avec la migration", une invite s'affiche pour demander à l'utilisateur de mettre à jour l'APK. Si l'utilisateur refuse cette mise à jour, le module continue de fonctionner et commence à accumuler des autorisations et des données :

Le téléphone doit être mis à jour


Figure 2 : Si le module de framework nécessite une mise à jour pour assurer la compatibilité des fonctionnalités, une invite s'affiche pour demander à l'utilisateur d'effectuer la mise à jour et de redémarrer son appareil. Si l'utilisateur refuse cette mise à jour, le module continue de fonctionner et commence à accumuler des autorisations et des données :

L'APK doit être mis à jour


Figure 3 : Une icône de chargement s'affiche pendant le processus de migration, avec un texte expliquant que les données sont en cours de synchronisation :

Synchronisation des données

Données dédupliquées

Si le module de framework a commencé à acquérir des données et des autorisations avant qu'une migration ou une restauration basée sur le cloud ne soit effectuée, les règles suivantes s'appliquent.

Autorisations

Si des autorisations sont présentes dans le module de framework, toutes les autorisations en double acquises à partir de l'APK sont ignorées lors du processus de migration.

Données

Lors de la migration, les données en double provenant de l'APK sont ignorées. Une préférence est accordée aux données plus récentes du module.

Les données sont dédupliquées au niveau du clientRecordId si l'ID d'enregistrement est fourni par le client. Dans le cas contraire, les intervalles de temps (startTime et endTime pour les enregistrements internes et time pour les enregistrements instantanés) sont traités comme une clé, ainsi que le type de données et le nom de package de l'application.

Modifications apportées au SDK Jetpack

Le SDK Jetpack sert de point d'intégration commun pour l'APK de Santé Connect et les API du framework Santé Connect.

Les OEM peuvent commencer l'intégration à Jetpack 13. Ainsi, lorsque Jetpack 14 sera disponible, vous pourrez utiliser la nouvelle bibliothèque et la compiler dans Android 14.

Nous allons publier une nouvelle version du SDK, qui facilitera la transition vers Android 14. Vous devrez apporter quelques modifications à votre intégration existante pour assurer une transition en douceur.

Déclaration d'autorisations

Dans Android 13, vous déclarez les autorisations à l'aide d'un format personnalisé, dans un fichier de ressources lié au fichier manifeste :

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

Pour prendre en charge Android 14, les développeurs doivent passer au format d'autorisation standard :

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

Ouvrir Santé Connect

La plupart des applications tierces comportent un bouton qui ouvre l'application Santé Connect, comme le bouton "Manage Access" (Gérer l'accès) dans Fitbit.

Dans Android 13, vous pouvez ouvrir l'application Santé Connect à l'aide du nom de package ou via l'action androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

Dans Android 14, vous devrez utiliser une action d'intent spécifiée dans le SDK Jetpack, dont les valeurs diffèrent selon la version d'Android concernée :

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

Obtenir le client Santé Connect

Nous avons créé une seule API appelée sdkStatus, disponible dans Jetpack 11, pour remplacer deux autres API obsolètes : IsSdkSupported() et isProviderAvailable().

Modifications apportées à l'API d'enregistrement des séances

Quatre sous-types ExerciseSession ont été supprimés dans la version alpha10 :

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Comme pour ExerciseSessionRecord, SleepStage deviendra un sous-type de SleepSession.

Les sous-types ExerciseSessionRecord et les modifications de SleepSession seront publiés dans le cadre de la mise à jour du SDK d'avril.

Mise à jour des types de séances d'entraînement

Les types de séances d'entraînement ci-dessous ne seront plus acceptés et seront ajoutés en tant que types de segment à une date ultérieure :

  • 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

Types de remplacement :

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Gestion des journaux de modifications

Les journaux de modifications ne seront pas migrés lors du passage de l'APK à Android 14.

Une fois la migration terminée, vous commencerez à recevoir des exceptions TOKEN_EXPIRED ou TOKEN_INVALID. Vous devrez les gérer de la manière suivante (par ordre de préférence) :

1. Lire et dédupliquer toutes les données depuis l'horodatage indiquant la dernière lecture ou pour les 30 derniers jours

Stockez l'horodatage de la dernière fois que l'application a lu des données à partir de Santé Connect. À l'expiration du jeton, les données devront être lues à nouveau à partir de cette date ou, le cas échéant, à partir des 30 derniers jours, et dédupliquées par rapport aux données lues précédemment à l'aide de l'UUID.

2. Lire les données depuis l'horodatage de la dernière lecture

Établissez un horodatage qui indique quand les données ont été lues pour la dernière fois à partir de Santé Connect. À l'expiration du jeton, lisez toutes les données après cette date.

3. Supprimer et relire les données des 30 derniers jours

Supprimez toutes les données lues dans Santé Connect au cours des 30 derniers jours, puis lisez-les à nouveau (comme c'est le cas lorsque les applications s'intègrent pour la première fois à Santé Connect).

4. Ne rien faire (ex. : relire les données des 30 derniers jours sans les dédupliquer)

Cette méthode doit être utilisée en dernier recours et fait courir le risque d'afficher des données en double. À la place, nous recommandons aux développeurs d'explorer les options 1 à 3, car les UUID devraient déjà être en place.

Tester les API Android 14 avec le SDK Jetpack

Le SDK Jetpack Android 14 est prévu pour le 7 juin 2023, avec la version bêta 3 d'Android 14. Vous devrez commencer à compiler votre application pour Android 14 afin de pouvoir utiliser le SDK Jetpack Android 14.

Si vous souhaitez tester votre solution sur les versions Preview développeur Android avant le 7 juin, adressez-vous à votre contact Google pour en savoir plus.

Si vous souhaitez tester votre solution sur la version bêta 3, apportez les modifications suivantes dans l'APK :

  1. Définissez compileSDKPreview = UpsideDownCake.
  2. Mettez à jour le fichier manifeste pour inclure un intent pour Android 14 :
# 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>

Personnalisation pour les OEM

Dans Android 14, les éléments de confidentialité et de gestion des données de Santé Connect se trouvent dans les paramètres système.

Pour que les écrans de gestion et d'autorisation des données s'intègrent au mieux à l'appareil, Santé Connect propose une thématisation OEM basée sur l'utilisation de superpositions personnalisées.

Pour en savoir plus sur les styles OEM, consultez la documentation des services Google Mobile de Santé Connect.