跟踪睡眠时段

本指南与健康数据共享版本 1.1.0-alpha11 兼容。

健康数据共享提供睡眠时段数据类型，用于存储有关用户睡眠的信息，例如夜间睡眠时段或白天小睡时段。SleepSessionRecord 数据类型用于表示这些会话。

通过时段，用户可以衡量一段时间内基于时间的性能，例如连续心率或位置数据。

SleepSessionRecord 时段包含记录睡眠阶段的数据，例如 AWAKE、SLEEPING 和 DEEP。

子类型数据是“属于”某时段的数据，仅当与父时段一起被读取时才有意义。例如，睡眠阶段。

功能的适用范围

相应数据类型没有功能可用性标志。

所需权限

对睡眠会话的访问受以下权限保护：

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

在 Play 管理中心内为您的应用声明这些权限，并在应用的清单中声明这些权限：

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

您有责任声明您打算在设备和应用中使用的所有相应权限。您还应在每次使用权限之前检查用户是否已授予相应权限

常规准则

以下是一些有关如何在 Health Connect 中使用睡眠时段的最佳实践准则。

  • 时段应被用于添加特定睡眠时段的数据，或者用于睡眠：
suspend fun writeSleepSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            SleepSessionRecord(
                startTime = Instant.parse("2022-05-10T23:00:00.000Z"),
                startZoneOffset = ZoneOffset.of("-08:00"),
                endTime = Instant.parse("2022-05-11T07:00:00.000Z"),
                endZoneOffset = ZoneOffset.of("-08:00"),
                title = "My Sleep"
            ),
        )
    )
}
  • 时段不应被用于常规测量，例如每日步数。
  • 子类型数据不包含 UID，但关联的数据具有各不相同的 UID。
  • 子类型数据需要在时段中与不重叠的依序时间戳对应。不过，允许设置间隔。
  • 如果用户想让数据关联到时段（并作为时段的一部分进行跟踪）而不是持续记录，时段非常有用。

睡眠时段

您可以在 Health Connect 中读取或写入睡眠数据。睡眠数据会显示为时段，且可分为 8 个各不相同的睡眠阶段：

  • UNKNOWN：未指明或不清楚用户是否正在睡觉。
  • AWAKE：用户在一个睡眠周期内（而不是在白天）处于清醒状态。
  • SLEEPING：对睡眠的通用或粗略描述。
  • OUT_OF_BED：用户在睡眠时段下床。
  • AWAKE_IN_BED：用户在床上但处于清醒状态。
  • LIGHT：用户处于浅层睡眠周期。
  • DEEP：用户处于深层睡眠周期。
  • REM：用户处于快速眼动睡眠周期。

这些值表示用户在特定时间范围内的睡眠类型。写入睡眠阶段是可选操作，但建议执行（如果可以的话）。

写入睡眠时段

SleepSessionRecord 数据类型包含 2 个部分：

  1. 整个时段（跨越睡眠的全部时长）。
  2. 睡眠时段的各个阶段，例如浅层睡眠或深层睡眠。

下面展示了如何插入不包含阶段的睡眠时段：

SleepSessionRecord(
      title = "weekend sleep",
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
)

下面展示了如何添加涵盖睡眠时段全部时长的各个阶段：

val stages = listOf(
    SleepSessionRecord.Stage(
        startTime = START_TIME
        endTime = END_TIME,
        stage = SleepSessionRecord.STAGE_TYPE_SLEEPING,
    )
)

SleepSessionRecord(
        title = "weekend sleep",
        startTime = START_TIME,
        endTime = END_TIME,
        startZoneOffset = START_ZONE_OFFSET,
        endZoneOffset = END_ZONE_OFFSET,
        stages = stages,
)

读取睡眠时段

对于返回的每个睡眠时段，您应检查是否也有睡眠阶段数据：

suspend fun readSleepSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                SleepSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (sleepRecord in response.records) {
        // Retrieve relevant sleep stages from each sleep record
        val sleepStages = sleepRecord.stages
    }
}

删除睡眠时段

下面展示了如何删除时段。在此示例中，我们使用了睡眠时段：

suspend fun deleteSleepSession(
    healthConnectClient: HealthConnectClient,
    sleepRecord: SleepSessionRecord,
) {
    val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
    healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)
}