Développer des expériences d'entraînement avec Santé Connect

Si vous souhaitez créer une expérience d'entraînement dans votre application, vous pouvez utiliser Santé Connect pour effectuer les actions suivantes :

• Écrire des sessions d'exercice
• Écrire des itinéraires d'entraînement
• Écrire des métriques d'entraînement telles que la fréquence cardiaque, la vitesse et la distance
• Lire les données d'entraînement provenant d'autres applications

Ce guide explique comment créer ces fonctionnalités d'entraînement. Il aborde les types de données, l'exécution en arrière-plan, les autorisations, les workflows recommandés et les bonnes pratiques.

Présentation : Créer un outil complet de suivi des entraînements

Vous pouvez créer une expérience complète de suivi des entraînements à l'aide de Santé Connect en suivant ces étapes clés :

• Implémenter correctement les autorisations basées sur les autorisations de santé.
• Enregistrement de sessions à l'aide de ExerciseSessionRecord.
• Écrire les données d'entraînement de manière cohérente pendant la séance.
• Gérer correctement l'exécution en arrière-plan pour vérifier la capture continue des données.
• Lecture des données de session pour les récapitulatifs et les analyses post-entraînement.

Ce workflow permet l'interopérabilité avec d'autres applications Santé Connect et vérifie l'accès aux données contrôlé par l'utilisateur.

Avant de commencer

Avant d'implémenter des fonctionnalités d'entraînement :

• Intégrez Santé Connect à l'aide de la dépendance appropriée.
• Créez une instance HealthConnectClient.
• Vérifiez que votre application implémente des flux d'autorisation d'exécution basés sur les autorisations de santé.
• Si votre workflow utilise le GPS, configurez l'autorisation de localisation et un service de premier plan.

Concepts clés

Santé Connect représente les données d'entraînement à l'aide de quelques composants de base. Un ExerciseSessionRecord sert d'enregistrement central pour un entraînement. Il contient des informations telles que les heures de début et de fin, et le type d'exercice. Au cours d'une session, différents types de données tels que HeartRateRecord ou SpeedRecord peuvent être enregistrés. Pour les activités en extérieur, ExerciseRoute stocke les données GPS, qui sont associées à la session correspondante.

Sessions d'exercice

ExerciseSessionRecord est l'enregistrement central des données d'entraînement, qui représente une seule séance d'entraînement. Chaque enregistrement contient les informations suivantes :

• startTime
• endTime
• exerciseType
• Métadonnées de session facultatives (titre, notes)

Une ExerciseSessionRecord peut également contenir des parcours d'exercice, des tours et des segments dans ses données. De plus, d'autres types de données, tels que HeartRateRecord ou SpeedRecord, peuvent être enregistrés au cours d'une session et y être associés.

Types de données associés

Les données associées aux séances d'entraînement sont représentées par des types d'enregistrements individuels. Voici quelques types courants :

• HeartRateRecord : représente une série de mesures de la fréquence cardiaque.
• SpeedRecord : représente une série de mesures de vitesse.
• DistanceRecord : représente la distance parcourue entre les lectures.
• TotalCaloriesBurnedRecord : représente le nombre total de calories brûlées entre les lectures.
• ElevationGainedRecord : représente le dénivelé positif entre les lectures.
• StepsCadenceRecord : représente la cadence des pas entre les lectures.
• PowerRecord : représente la puissance de sortie entre les lectures, courante dans les activités comme le cyclisme.

Pour obtenir la liste complète des types de données, consultez Types de données Santé Connect.

Itinéraires d'exercice

Vous pouvez associer un itinéraire à vos entraînements en extérieur à l'aide de ExerciseRoute. Les routes se composent d'objets ExerciseRoute.Location séquentiels, chacun contenant :

• Latitude et longitude
• Altitude facultative
• Cap facultatif
• Informations sur la précision
• Code temporel

Associer des routes de session

Un ExerciseRoute contient les données de localisation séquentielles d'une séance d'exercice. Il n'est pas traité comme un enregistrement indépendant dans Santé Connect. Au lieu de cela, vous fournissez des données ExerciseRoute lorsque vous insérez ou mettez à jour un ExerciseSessionRecord.

Considérations relatives au développement

Les applications de suivi d'entraînement doivent souvent s'exécuter pendant de longues périodes, fréquemment en arrière-plan lorsque l'écran est éteint. Lorsque vous créez vos fonctionnalités d'entraînement, il est important de réfléchir à la manière de gérer l'exécution en arrière-plan et de demander les autorisations nécessaires pour les données d'entraînement.

Exécution en arrière-plan

Les applications d'entraînement s'exécutent généralement avec l'écran éteint. Dans cet état, vous devez utiliser :

• Services de premier plan pour l'échantillonnage de la position et des capteurs
• WorkManager pour l'écriture ou la synchronisation différées
• Stratégies de traitement par lot pour l'écriture d'enregistrements réguliers

Assurez la continuité en conservant le même ID de session pour toutes les écritures.

Autorisations

Votre application doit demander les autorisations Santé Connect appropriées avant de lire ou d'écrire des données d'entraînement. Les autorisations courantes pour les entraînements incluent les séances d'exercice, les itinéraires d'exercice et les métriques telles que la fréquence cardiaque ou la vitesse. et vous devriez pouvoir :

• Séances d'exercice : autorisations de lecture et d'écriture pour ExerciseSessionRecord.
• Parcours sportifs : autorisations de lecture et d'écriture pour ExerciseRoute.
• Fréquence cardiaque : autorisations de lecture et d'écriture pour HeartRateRecord.
• Vitesse : autorisations de lecture et d'écriture pour SpeedRecord.
• Distance : autorisations de lecture et d'écriture pour DistanceRecord.
• Calories : autorisations de lecture et d'écriture pour TotalCaloriesBurnedRecord.
• Élévation gagnée : autorisations de lecture et d'écriture pour ElevationGainedRecord.
• Cadence de marche : autorisations de lecture et d'écriture pour StepsCadenceRecord.
• Power : autorisations de lecture et d'écriture pour PowerRecord.
• Étapes : autorisations de lecture et d'écriture pour StepsRecord.

L'exemple suivant montre comment demander plusieurs autorisations pour une séance d'entraînement qui inclut des données sur l'itinéraire, la fréquence cardiaque, la distance, les calories, la vitesse et les pas :

Après avoir créé une instance de client, votre application doit demander des autorisations à l'utilisateur. Les utilisateurs doivent être autorisés à accorder ou à refuser des autorisations à tout moment.

Pour ce faire, créez un ensemble d'autorisations pour les types de données requis. Assurez-vous d'abord que les autorisations de l'ensemble sont déclarées dans votre fichier manifeste Android.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class),
  HealthPermission.getReadPermission(ExerciseRoute::class),
  HealthPermission.getWritePermission(ExerciseRoute::class),
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(SpeedRecord::class),
  HealthPermission.getWritePermission(SpeedRecord::class),
  HealthPermission.getReadPermission(DistanceRecord::class),
  HealthPermission.getWritePermission(DistanceRecord::class),
  HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

Utilisez getGrantedPermissions pour voir si votre application dispose déjà des autorisations requises accordées. Si ce n'est pas le cas, utilisez createRequestPermissionResultContract pour demander ces autorisations. L'écran des autorisations de Santé Connect s'affiche.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Étant donné que les utilisateurs peuvent accorder ou révoquer des autorisations à tout moment, votre application doit vérifier les autorisations à chaque fois avant de les utiliser et gérer les scénarios dans lesquels une autorisation est perdue.

Pour demander des autorisations, appelez la fonction checkPermissionsAndRun :

if (!granted.containsAll(PERMISSIONS)) {
    requestPermissions.launch(PERMISSIONS)
    // Check if required permissions are not granted, and return
  }
// Permissions already granted; proceed with inserting or reading data

Si vous n'avez besoin de demander des autorisations que pour un seul type de données, comme la fréquence cardiaque, n'incluez que ce type de données dans votre ensemble d'autorisations :

L'accès à la fréquence cardiaque est protégé par les autorisations suivantes :

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

Pour ajouter la fonctionnalité de fréquence cardiaque à votre application, commencez par demander des autorisations pour le type de données HeartRateRecord.

Voici l'autorisation que vous devez déclarer pour pouvoir écrire la fréquence cardiaque :

<application>
  <uses-permission
android:name="android.permission.health.WRITE_HEART_RATE" />
...
</application>

Pour lire la fréquence cardiaque, vous devez demander les autorisations suivantes :

<application>
  <uses-permission
android:name="android.permission.health.READ_HEART_RATE" />
...
</application>

Implémenter une séance d'entraînement

Cette section décrit le workflow recommandé pour enregistrer les données d'entraînement.

Démarrer la session

Pour créer un entraînement :

1. Générez un ID de session unique : vérifiez que cet ID est stable. Si le processus de votre application est arrêté et redémarré, vous devez pouvoir reprendre l'utilisation du même ID pour éviter les sessions fragmentées.
2. Définissez un metadata.clientRecordId pour éviter les doublons lors des nouvelles tentatives de synchronisation.
3. Rédige un ExerciseSessionRecord : inclue l'heure de début.
4. Commencez à collecter les données de type et les données GPS : ne commencez qu'une fois l'enregistrement de la session correctement initialisé.

Exemple :

val sessionId = UUID.randomUUID().toString()
val sessionClientId = UUID.randomUUID().toString()

val session = ExerciseSessionRecord(
    id = sessionId,
    exerciseType = ExerciseType.EXERCISE_TYPE_RUNNING,
    startTime = Instant.now(),
    endTime = null,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))

Enregistrer des itinéraires d'exercice

Pour en savoir plus sur la lecture des conseils, consultez Lire les données brutes.

Lorsque vous enregistrez un itinéraire d'exercice, vous devez regrouper vos données par lots. Cela signifie qu'au lieu d'enregistrer chaque point GPS individuellement, vous collectez un groupe de points et les enregistrez tous en même temps en un seul appel.

C'est important, car chaque fois que votre application lit ou écrit des données dans Santé Connect, elle utilise une petite quantité de batterie et de puissance de traitement.

Le code suivant montre comment enregistrer des données par lots :

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

Mettre fin à une session

Après avoir arrêté la collecte des données :

• Mettez à jour l'enregistrement : votre application met à jour ExerciseSessionRecord avec un endTime.
• Finaliser les données : vous pouvez calculer des valeurs récapitulatives (comme la distance totale ou l'allure moyenne) et les écrire en tant qu'enregistrements supplémentaires.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

Lire les données d'entraînement

Les applications peuvent lire les séances d'exercice et les données associées pour résumer l'activité, fournir des informations sur la santé ou synchroniser les données avec un serveur externe. Par exemple, vous pouvez lire un ExerciseSessionRecord, puis interroger le HeartRateRecord ou le DistanceRecord qui s'est produit au cours de ce même intervalle de temps.

Si vous devez synchroniser les données d'entraînement avec un serveur backend ou maintenir le datastore de votre application à jour avec Santé Connect, utilisez ChangeLogs. Cela vous permet de récupérer une liste des enregistrements insérés, mis à jour ou supprimés depuis un moment précis, ce qui est plus efficace que de suivre manuellement les modifications ou de lire toutes les données à plusieurs reprises. Pour en savoir plus, consultez Synchroniser des données avec Santé Connect.

Lire les sessions

Pour lire les sessions d'exercice, utilisez un ReadRecordsRequest avec ExerciseSessionRecord comme type. Vous filtrez généralement cette valeur par une plage de temps spécifique.

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = ExerciseSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

Lire des itinéraires

Bien que les données ExerciseRoute soient écrites dans le cadre d'une séance d'exercice, elles doivent être lues séparément. Utilisez la méthode getExerciseRoute() avec l'ID de la session pour lire les données de son itinéraire :

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

Types de données de lecture

Pour lire des données précises (comme la fréquence cardiaque) qui se sont produites au cours d'une session, utilisez les startTime et endTime de la session pour filtrer la requête pour ce type de données.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.records) {
        for (sample in heartRateRecord.samples) {
            val bpm = sample.beatsPerMinute
        }
    }
}

Bonnes pratiques

Suivez ces consignes pour améliorer la fiabilité des données et l'expérience utilisateur :

• Fréquence d'écriture
  • Suivi actif(premier plan) : pour les entraînements actifs, écrivez les données dès qu'elles sont disponibles ou à un intervalle maximal de 15 minutes.
  • Synchronisation en arrière-plan : utilisez WorkManager pour les écritures différées. Visez un intervalle de 15 minutes pour trouver un équilibre entre les données en temps réel et l'efficacité de la batterie.
  • Regroupement : n'écrivez pas chaque événement de capteur individuellement. Fragmentez vos demandes. Santé Connect gère jusqu'à 1 000 enregistrements par requête d'écriture.
• Conservez des ID de session stables et uniques : utilisez des identifiants cohérents pour vos sessions. Si une séance est modifiée ou mise à jour, l'utilisation du même ID permet d'éviter qu'elle soit traitée comme un nouvel entraînement distinct.
• Utilisez le traitement par lot pour les types de données et les points de route : pour réduire la surcharge d'entrée/sortie et préserver l'autonomie de la batterie, regroupez vos points de données dans un seul appel insertRecords au lieu d'écrire chaque point individuellement.

• Évitez d'écrire des données en double : utilisez des ID client Lorsque vous créez des enregistrements, définissez un metadata.clientRecordId. Santé Connect utilise cette valeur pour identifier les enregistrements uniques. Si vous tentez d'écrire un enregistrement avec un clientRecordId qui existe déjà, Santé Connect ignorera le doublon ou mettra à jour l'enregistrement existant au lieu d'en créer un. Définir un metadata.clientRecordId est le moyen le plus efficace d'éviter les doublons lors des nouvelles tentatives de synchronisation ou des réinstallations d'applications.

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )
  

• Vérifiez les données existantes : avant de synchroniser, interrogez la plage de dates pour voir si des enregistrements de votre application existent déjà.

• Validez la précision du GPS : filtrez les échantillons GPS de faible précision (par exemple, les points avec un rayon de précision horizontale élevé) avant d'écrire dans ExerciseRoute pour vérifier que la carte est propre et professionnelle.

• Assurez-vous que les codes temporels ne se chevauchent pas : vérifiez qu'une nouvelle session ne commence pas avant la fin de la précédente. Les sessions qui se chevauchent peuvent entraîner des conflits dans les tableaux de bord de remise en forme et les calculs récapitulatifs.

• Fournissez des justifications claires pour les autorisations : utilisez le flux Permission.createIntent pour expliquer pourquoi votre application a besoin d'accéder aux données de santé, par exemple "Pour cartographier vos courses et calculer les calories brûlées".

• Prise en charge de la pause et de la reprise : vérifiez que votre application gère correctement les pauses. Lorsqu'un utilisateur met en pause l'enregistrement, arrêtez de collecter les points de route et les types de données afin que l'allure et la durée moyennes restent précises.

• Tester les sessions de longue durée : surveillez la consommation de batterie pendant les sessions de plusieurs heures pour vérifier que votre intervalle de regroupement et l'utilisation des capteurs ne déchargent pas l'appareil.

• Alignez les codes temporels sur les fréquences des capteurs : faites correspondre les codes temporels de vos enregistrements à la fréquence réelle de vos capteurs (par exemple, 1 Hz pour le GPS) afin de maintenir la haute fidélité des données.

Tests

Pour vérifier l'exactitude des données et offrir une expérience utilisateur de haute qualité, suivez ces stratégies de test et consultez la documentation officielle Tester les principaux cas d'utilisation.

Outils de validation

• Boîte à outils Santé Connect : utilisez cette application associée pour inspecter manuellement les enregistrements, supprimer les données de test et simuler des modifications de la base de données. C'est le meilleur moyen de vérifier que vos enregistrements sont stockés correctement.
• Tests unitaires avec FakeHealthConnectClient : utilisez la bibliothèque de test pour vérifier comment votre application gère les cas extrêmes, comme la révocation d'autorisations ou les exceptions d'API, sans avoir besoin d'un appareil physique.

Checklist pour la qualité

Architecture typique

Une implémentation d'entraînement inclut généralement les éléments suivants :

Dépannage

Étapes de débogage courantes

• Vérifier l'état de l'autorisation : appelez toujours getPermissionStatus() avant de tenter une opération de lecture ou d'écriture. Les utilisateurs peuvent révoquer les autorisations dans les paramètres système à tout moment.
• Vérifier le mode d'exécution : si votre application ne collecte pas de données en arrière-plan, vérifiez que vous avez déclaré les autorisations appropriées dans votre AndroidManifest.xml et que l'utilisateur n'a pas placé l'application en mode "Batterie limitée".