تتبُّع جلسات النوم

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha11 من Health Connect.

يوفّر Health Connect نوع بيانات جلسة النوم لتخزين معلومات حول نوم المستخدم، مثل جلسة ليلية أو قيلولة نهارية. يتم استخدام نوع البيانات 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>

أنت المسؤول عن الإفصاح عن جميع الأذونات المناسبة التي تنوي استخدامها في أجهزتك وتطبيقاتك. يجب أيضًا التأكّد من أنّ المستخدم قد منح كل إذن قبل استخدامه.

إرشادات عامة

في ما يلي بعض الإرشادات حول أفضل الممارسات المتعلقة بكيفية استخدام جلسات النوم في 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"
            ),
        )
    )
}

• يجب عدم استخدام الجلسات في القياسات العامة، مثل عدد الخطوات اليومية.
• لا تحتوي بيانات النوع الفرعي على معرّف فريد للمستخدم، ولكن البيانات المرتبطة بها تتضمّن معرّفات فريدة للمستخدمين.
• يجب أن تتوافق بيانات النوع الفرعي في جلسة مع طوابع زمنية متسلسلة لا تتداخل. ومع ذلك، يُسمح بالفجوات.
• تكون الجلسات مفيدة إذا كان المستخدم يريد ربط البيانات بجلسة (وتتبُّعها كجزء منها)، بدلاً من تسجيلها بشكل مستمر.

جلسات النوم

يمكنك قراءة بيانات النوم أو كتابتها في Health Connect. يتم عرض بيانات النوم على شكل جلسة، ويمكن تقسيمها إلى 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)
}