Développer des expériences de sommeil avec Santé Connect

Si vous souhaitez créer une expérience de suivi du sommeil dans votre application, vous pouvez utiliser Santé Connect pour effectuer les actions suivantes :

• Modifier les données de sessions de sommeil
• Écrire des données sur les phases de sommeil
• Écrire des données sur le sommeil, comme la fréquence cardiaque, la saturation en oxygène et la fréquence respiratoire
• Lire les données de sommeil provenant d'autres applications

Ce guide explique comment créer ces fonctionnalités de sommeil, en abordant 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 de suivi du sommeil complet

Vous pouvez créer une expérience complète de suivi du sommeil à l'aide de Santé Connect en suivant ces étapes principales :

• Implémenter correctement les autorisations basées sur les autorisations de santé.
• Enregistrement de sessions à l'aide de SleepSessionRecord.
• Écrire des types de données comme les phases de sommeil, la fréquence cardiaque et la saturation en oxygène de manière cohérente pendant la session.
• Gérer correctement l'exécution en arrière-plan pour vérifier la capture continue de données pendant la nuit.
• Lecture des données de session pour les résumés et analyses après le sommeil.

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 les fonctionnalités de sommeil :

• 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 Health Permissions.

Concepts clés

Santé Connect représente les données de sommeil à l'aide de quelques composants de base. Une SleepSessionRecord sert d'enregistrement central pour le sommeil. Elle contient des informations telles que les heures de début et de fin, ainsi que les phases de sommeil. Au cours d'une session, différents types de données peuvent être enregistrés, comme HeartRateRecord ou OxygenSaturationRecord.

Sessions de sommeil

Les données sur le sommeil sont représentées par SleepSessionRecord. Chaque enregistrement contient les informations suivantes :

• startTime
• endTime
• stages : liste de SleepSessionRecord.Stage incluant le sommeil profond, léger, paradoxal et l'éveil.
• Métadonnées de session facultatives (titre, notes)

Les applications peuvent écrire plusieurs types de données associés à une session.

Types de données

Voici les types de données courantes enregistrées lors d'une période de sommeil :

• SleepSessionRecord : enregistre la durée et les phases de sommeil, y compris le sommeil profond, léger, paradoxal et l'état de veille.
• HeartRateRecord : enregistre la fréquence cardiaque pendant le sommeil.
• OxygenSaturationRecord : enregistre la saturation en oxygène (SpO2) pendant le sommeil.
• RespiratoryRateRecord : enregistre la fréquence respiratoire pendant le sommeil.

Chaque type de données est stocké en tant qu'enregistrement individuel.

Considérations relatives au développement

Les applications de suivi du sommeil 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 de suivi du sommeil, 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 de sommeil.

Exécution en arrière-plan

Les applications de suivi du sommeil s'exécutent généralement la nuit avec l'écran éteint. Dans cet état, vous devez utiliser :

• Services de premier plan pour la collecte de données
• WorkManager pour l'écriture ou la synchronisation différées
• Stratégies de regroupement pour les écritures d'enregistrements réguliers de données précises telles que la fréquence cardiaque

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 de sommeil. Pour obtenir la liste complète des types de données, consultez Types de données Santé Connect. Les autorisations courantes pour le sommeil incluent les sessions de sommeil et les métriques telles que la fréquence cardiaque ou la saturation en oxygène.

L'accès au sommeil est protégé par les autorisations suivantes :

• android.permission.health.READ_SLEEP
• android.permission.health.WRITE_SLEEP

Pour ajouter la fonctionnalité de suivi du sommeil à votre application, commencez par demander des autorisations pour le type de données SleepSession.

Voici l'autorisation que vous devez déclarer pour pouvoir écrire des données de sommeil :

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

Pour lire les données de sommeil, vous devez demander les autorisations suivantes :

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

L'exemple suivant montre comment demander des autorisations pour une session de sommeil qui inclut des données sur la fréquence cardiaque, la saturation en oxygène et la fréquence respiratoire :

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(SleepSessionRecord::class),
  HealthPermission.getWritePermission(SleepSessionRecord::class),
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(OxygenSaturationRecord::class),
  HealthPermission.getWritePermission(OxygenSaturationRecord::class),
  HealthPermission.getReadPermission(RespiratoryRateRecord::class),
  HealthPermission.getWritePermission(RespiratoryRateRecord::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.

Implémenter une session de sommeil

Cette section décrit le workflow recommandé pour enregistrer les données de sommeil.

Pour aligner des types de données tels que HeartRateRecord ou OxygenSaturationRecord sur une session de sommeil, enregistrez-les avec des codes temporels compris entre startTime et endTime de la session. Santé Connect n'utilise pas d'identifiant de session pour associer les périodes de sommeil à des données précises. L'association est plutôt implicite par le biais d'intervalles de temps qui se chevauchent. Lorsque vous lisez des données de sommeil, vous pouvez utiliser la plage horaire d'une session pour interroger les types de données associés, comme indiqué dans Lecture des données de sommeil.

Écrire une session

Bien que des données précises telles que la fréquence cardiaque puissent être enregistrées tout au long d'une session de sommeil, SleepSessionRecord lui-même ne doit être écrit dans Santé Connect qu'une fois la session terminée, par exemple lorsque l'utilisateur se réveille. L'enregistrement doit inclure la session startTime, endTime et une liste des objets SleepSessionRecord.Stage enregistrés pendant la session, car SleepSessionRecord exige que endTime soit après startTime.

Pour écrire une session de sommeil :

1. Générez un ID d'enregistrement client unique.
2. Lorsque l'utilisateur se réveille ou que le suivi du sommeil est arrêté, rassemblez toutes les phases de sommeil et construisez un SleepSessionRecord.
3. Insérez l'enregistrement à l'aide de insertRecords.

Exemple :

val clientRecordId = UUID.randomUUID().toString()
val sessionStartTime = LocalDateTime.of(2023, 10, 30, 22, 0).toInstant(ZoneOffset.UTC)
val sessionEndTime = LocalDateTime.of(2023, 10, 31, 7, 0).toInstant(ZoneOffset.UTC)

val stages = mutableListOf<SleepSessionRecord.Stage>()
// Add recorded stages, for example:
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(3600),
    endTime = sessionStartTime.plusSeconds(7200),
    stage = SleepSessionRecord.STAGE_TYPE_LIGHT)
)
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(7200),
    endTime = sessionStartTime.plusSeconds(10800),
    stage = SleepSessionRecord.STAGE_TYPE_DEEP)
)
// ... other stages

val session = SleepSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    stages = stages,
    metadata = Metadata(clientRecordId = clientRecordId)
)

healthConnectClient.insertRecords(listOf(session))

Lire les données sur le sommeil

Les applications peuvent lire les sessions de sommeil 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 SleepSessionRecord, puis interroger le HeartRateRecord qui s'est produit au cours de ce même intervalle de temps.

Session de lecture avec données associées

Vous pouvez lire les périodes de sommeil à l'aide d'un ReadRecordsRequest avec SleepSessionRecord comme type d'enregistrement, filtré par plage de temps. Pour lire les données associées à une session donnée, envoyez une deuxième requête pour le type de données sélectionné, tel que HeartRateRecord, en filtrant par startTime et endTime de la session de sommeil.

L'exemple suivant montre comment lire les sessions de sommeil avec les données de fréquence cardiaque associées pour une plage de temps donnée :

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

    for (sleepRecord in response.records) {
        // Process each session
        val stages = sleepRecord.stages
        val notes = sleepRecord.notes

        // To read specific granular data (like heart rate) that occurred during
        // this session, use the session's startTime and endTime to filter
        // the request for that data type.
        val hrResponse = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    sleepRecord.startTime,
                    sleepRecord.endTime
                )
            )
        )
        for (heartRateRecord in hrResponse.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 le suivi actif du sommeil, é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 session est modifiée ou mise à jour, l'utilisation du même ID permet d'éviter qu'elle soit traitée comme une nouvelle session de sommeil distincte.
• Utilisez le traitement par lot pour les types de données : 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 = RespiratoryRateRecord(
      rate = 16.0,
      time = time,
      zoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "respiratory_rate_20231030_1"
      )
  )
  

• 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à.

• 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 analyser vos habitudes de sommeil".

• 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 taux de capteurs : faites correspondre les codes temporels de vos enregistrements à la fréquence réelle de vos capteurs pour 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 du suivi du sommeil 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".