睡眠セッションを記録する

このガイドは、Health Connect バージョン 1.1.0-alpha11 に対応しています。

ヘルスコネクトは、睡眠セッションのデータ型を提供し、ユーザーの睡眠に関する情報（夜間の睡眠や昼間の昼寝など）を保存します。これらのセッションを表すために SleepSessionRecord データ型が使用されます。

セッションにより、ユーザーは継続的な心拍数や位置情報など、時間ベースのパフォーマンスを一定期間にわたり測定できます。

SleepSessionRecord セッションには、睡眠ステージを記録するデータ（AWAKE、SLEEPING、DEEP など）が含まれます。

サブタイプ データはセッションに「属する」データで、親セッションと一緒に読み取られた場合にのみ意味のあるデータとなります。たとえば、睡眠ステージなどです。

機能の提供状況

このデータ型には機能の可用性フラグがありません。

必要な権限

睡眠セッションへのアクセスは、次の権限によって保護されています。

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

これらの権限は、アプリの Google 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"
            ),
        )
    )
}
  • セッションは、1 日の歩数などの一般的な測定には使用しないでください。
  • サブタイプ データには UID は含まれていませんが、関連データには区別できる UID が含まれています。
  • サブタイプ データはセッションの重複していない連続したタイムスタンプに沿っている必要があります。ただし、空白期間は許容されます。
  • セッションはデータを連続して記録するのではなく、データをセッションに関連付ける（およびセッションの一部としてトラッキングする）場合に便利です。

睡眠セッション

ヘルスコネクトで睡眠データの読み取りと書き込みができます。睡眠データはセッションとして表示され、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)
}