此页面由 Cloud Translation API 翻译。

跟踪睡眠时段

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

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

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

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

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

查看健康数据共享的适用范围

在尝试使用健康数据共享之前，您的应用应验证健康数据共享是否可在用户的设备上使用。并非所有设备都预安装了健康数据共享，或者健康数据共享可能处于停用状态。您可以使用 HealthConnectClient.getSdkStatus() 方法检查是否可用。

如何查看“健康数据共享”的适用范围

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

根据 getSdkStatus() 返回的状态，您可以引导用户从 Google Play 商店安装或更新健康数据共享（如果需要）。

功能的适用范围

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

所需权限

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

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

如要向应用添加睡眠会话功能，请先请求 SleepSession 数据类型的写入权限。

您需要声明以下权限才能写入睡眠会话：

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

如需读取睡眠时段，您需要请求以下权限：

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

向用户请求权限

创建客户端实例后，应用需要向用户请求权限。用户必须能够随时授予或拒绝权限。

为此，请为所需的数据类型创建一组权限。先确保此集中的权限已在 Android 清单中声明。

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(SleepSessionRecord::class),
  HealthPermission.getWritePermission(SleepSessionRecord::class)
)

使用 getGrantedPermissions 查看您的应用是否已获得所需的权限。如不具备，请使用 createRequestPermissionResultContract 请求这些权限。系统随即会显示“健康数据共享”权限界面。

// 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)
  }
}

由于用户可以随时授予或撤消权限，因此您的应用需要定期检查已授予的权限，并应对权限丢失的情况。

支持的聚合

以下是 SleepSessionRecord 的可用汇总值：

SLEEP_DURATION_TOTAL

常规准则

以下是一些有关如何在健康数据共享中处理睡眠时段的最佳实践准则。

时段应被用于添加特定睡眠时段的数据，或者用于睡眠：

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 个部分：

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

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

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)
}