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 opérations suivantes :

• Modifier les données de session de sommeil
• Modifier les données de phase de sommeil
• Modifier les données de sommeil telles que 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 suivi complet du sommeil

Vous pouvez créer une expérience complète de suivi du sommeil à l'aide de Santé Connect en procédant comme suit :

• Implémenter correctement les autorisations en fonction des autorisations de santé.
• Enregistrer les sessions à l'aide de SleepSessionRecord.
• Écrire des types de données tels que 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 des données pendant la nuit.
• Lire les données de session pour les récapitulatifs et les 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'autorisations d'exécution basés sur les autorisations de santé.

Concepts clés

Santé Connect représente les données de sommeil à l'aide de quelques composants principaux. Un SleepSessionRecord sert d'enregistrement central pour le sommeil, contenant des détails tels 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 tels que HeartRateRecord ou OxygenSaturationRecord peuvent être enregistrés.

Sessions de sommeil

Les données de sommeil sont représentées par SleepSessionRecord. Chaque enregistrement stocke les éléments suivants :

• startTime
• endTime
• stages: liste de SleepSessionRecord.Stage, y compris le sommeil profond, léger, paradoxal et éveillé.
• 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

Les types de données courants enregistrés lors d'une session de sommeil incluent les suivants :

• SleepSessionRecord: enregistre la durée et les phases de sommeil, y compris le sommeil profond, léger, paradoxal et éveillé.
• 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 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 pendant la nuit lorsque l'écran est éteint. Dans cet état, vous devez utiliser les éléments suivants :

• Services de premier plan pour la collecte de données
• WorkManager pour l'écriture ou la synchronisation différée
• Stratégies de traitement par lot pour les écritures régulières d'enregistrements de données granulaires, telles que la fréquence cardiaque

Maintenez la continuité en conservant l'ID de session cohérent dans 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 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 de fréquence cardiaque, de saturation en oxygène et de 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 l'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 horodatages compris entre startTime et endTime de la session. Santé Connect n'utilise pas d'identifiant de session pour lier les sessions de sommeil à des données granulaires. L'association est plutôt implicite via des intervalles de temps qui se chevauchent. Lorsque vous lisez des données de sommeil, vous pouvez utiliser la plage de temps 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 granulaires telles que la fréquence cardiaque puissent être enregistrées tout au long d'une session de sommeil, le 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, ainsi qu'une liste d'SleepSessionRecord.Stage objets enregistrés pendant la session, car SleepSessionRecord nécessite 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é, collectez toutes les phases de sommeil et créez 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))

Lecture des données de sommeil

Les applications peuvent lire les sessions de sommeil et les données associées pour résumer l'activité, fournir des insights 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 pendant le même intervalle de temps.

Lire une session avec des données associées

Vous pouvez lire les sessions de sommeil à l'aide d'un ReadRecordsRequest avec SleepSessionRecord comme type d'enregistrement, filtré par une plage de temps. Pour lire les données associées d'une session donnée, effectuez 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 :

• Écrivez fréquemment pendant le suivi actif : pour le suivi actif, écrivez les données dès qu'elles sont disponibles ou à un intervalle maximal de 15 minutes.
• Utilisez WorkManager pour les synchronisations 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.
• Regroupez les requêtes d'écriture par lot : n'écrivez pas chaque événement de capteur individuellement. Regroupez vos requêtes. 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 empêche qu'elle soit traitée comme une nouvelle session 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 l'utilise pour identifier les enregistrements uniques. Si vous tentez d'écrire un enregistrement avec un clientRecordId qui existe déjà, Santé Connect ignore le doublon ou met à jour l'enregistrement existant au lieu d'en créer un. La définition d'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 temps pour voir si des enregistrements de votre application existent déjà.
• Assurez-vous que les horodatages ne se chevauchent pas : vérifiez qu'une nouvelle session ne démarre 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 l'autorisation : utilisez le flux Permission.createIntent pour expliquer pourquoi votre application a besoin d'accéder aux données de santé, par exemple : "Pour surveiller les tendances de votre tension artérielle et fournir des insights".
• Testez les sessions de longue durée : surveillez la consommation de la batterie pendant les sessions de plusieurs heures pour vérifier que votre intervalle de traitement par lot et l'utilisation des capteurs ne déchargent pas l'appareil.
• Alignez les horodatages sur les taux des capteurs : faites correspondre les horodatages de vos enregistrements à la fréquence réelle de vos capteurs pour maintenir une haute fidélité des données.

Tests

Pour vérifier l'exactitude des données et offrir une expérience utilisateur de 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 complémentaire pour inspecter manuellement les enregistrements, supprimer les données de test et simuler des modifications dans la base de données. Il s'agit du 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, tels que la révocation d'autorisation ou les exceptions d'API sans avoir besoin d'un appareil physique.

Checklist pour la qualité

Architecture type

Une implémentation de suivi du sommeil inclut généralement les éléments suivants :

Dépannage

Étapes de débogage courantes