수면 세션 추적

이 가이드는 Health Connect 버전 1.1.0-alpha11과 호환됩니다.

헬스 커넥트는 수면 세션 데이터 유형을 제공하여 야간 세션이나 낮잠과 같은 사용자의 수면에 관한 정보를 저장합니다. SleepSessionRecord 데이터 유형은 이러한 세션을 나타내는 데 사용됩니다.

세션을 통해 사용자는 연속 심박수나 위치 데이터와 같은 일정 기간 동안의 시간 기반 성능을 측정할 수 있습니다.

SleepSessionRecord 세션에는 AWAKE, SLEEPING, DEEP 등 수면 단계를 기록하는 데이터가 포함됩니다.

하위유형 데이터는 세션에 '속하는' 데이터로, 상위 세션과 함께 읽을 때만 의미가 있습니다. 예를 들어 수면 단계입니다.

기능 사용 가능 여부

이 데이터 유형에는 기능 사용 가능 여부 플래그가 없습니다.

필수 권한

수면 세션에 대한 액세스는 다음 권한으로 보호됩니다.

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

앱의 Play Console과 앱의 매니페스트에서 다음 권한을 선언합니다.

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

기기와 앱에서 사용하려는 모든 적절한 권한을 선언해야 합니다. 사용하기 전에 각 권한이 사용자에게 부여되었는지도 확인해야 합니다.

일반 안내

다음은 헬스 커넥트에서 수면 세션으로 작업하는 방법에 관한 권장사항 가이드라인입니다.

  • 세션은 특정 수면 세션의 데이터를 추가하거나 수면을 위해 사용해야 합니다.
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가 있습니다.
  • 하위유형 데이터는 세션에서 겹치지 않는 순차적 타임스탬프를 사용하여 정렬되어야 합니다. 간격은 허용됩니다.
  • 세션은 사용자가 데이터를 계속 기록하기보다는 세션과 연결하고 세션의 일부로 추적하려는 경우에 유용합니다.

수면 세션

헬스 커넥트에서 수면 데이터를 읽거나 쓸 수 있습니다. 수면 데이터는 세션으로 표시되며 8가지 고유한 수면 단계로 나눌 수 있습니다.

  • UNKNOWN: 사용자가 수면 중인지 지정되지 않았거나 알 수 없습니다.
  • AWAKE: 사용자가 낮이 아닌 수면 주기 내에서 깨어 있습니다.
  • SLEEPING: 일반적이거나 상세하지 않은 수면 설명입니다.
  • OUT_OF_BED: 사용자가 수면 세션 중에 침대에서 나옵니다.
  • AWAKE_IN_BED: 사용자가 침대에서 깨어 있습니다.
  • LIGHT: 사용자가 얕은 수면 주기에 있습니다.
  • DEEP: 사용자가 깊은 수면 주기에 있습니다.
  • REM: 사용자가 렘수면 주기에 있습니다.

이러한 값은 시간 범위 내에서 사용자가 경험하는 수면 유형을 나타냅니다. 수면 단계 작성은 선택사항이지만 가능한 경우 권장합니다.

수면 세션 쓰기

SleepSessionRecord 데이터 유형은 두 부분으로 구성됩니다.

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