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

يتوافق هذا الدليل مع الإصدار ‎1.1.0-alpha12 من Health Connect أو الإصدارات الأحدث.

يوفّر Health Connect نوع بيانات فترة النوم لتخزين معلومات عن نوم المستخدم، مثل فترة النوم الليلية أو القيلولة النهارية. يتم استخدام نوع البيانات SleepSessionRecord لتمثيل هذه الجلسات.

تتيح الجلسات للمستخدمين قياس الأداء المستند إلى الوقت على مدار فترة زمنية، مثل معدّل نبضات القلب المستمر أو بيانات الموقع الجغرافي.

تتضمّن جلسات "SleepSessionRecord" بيانات تسجّل مراحل النوم، مثل AWAKE وSLEEPING وDEEP.

بيانات النوع الفرعي هي بيانات "تنتمي" إلى جلسة ولا تكون ذات معنى إلا عند قراءتها مع جلسة رئيسية. على سبيل المثال، مرحلة النوم.

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

التحقّق من توفّر Health Connect

قبل محاولة استخدام Health Connect، يجب أن يتأكّد تطبيقك من توفُّر Health Connect على جهاز المستخدم. قد لا يكون تطبيق Health Connect مثبَّتًا مسبقًا على جميع الأجهزة أو قد يكون غير مفعَّل. يمكنك التحقّق من توفّره باستخدام طريقة HealthConnectClient.getSdkStatus().

كيفية التحقّق من توفّر Health Connect

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata"
    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()، يمكنك توجيه المستخدم لتثبيت Health Connect أو تحديثه من "متجر 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 أولاً. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class)
    )
 استخدِم getGrantedPermissions لمعرفة ما إذا كان تطبيقك قد حصل على الأذونات المطلوبة. وإذا لم يكن الأمر كذلك، استخدِم createRequestPermissionResultContract لطلب هذه الأذونات. سيؤدي ذلك إلى عرض شاشة أذونات Health Connect. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 بما أنّ المستخدمين يمكنهم منح الأذونات أو إبطالها في أي وقت، يحتاج تطبيقك إلى التحقّق من الأذونات في كل مرة قبل استخدامها والتعامل مع السيناريوهات التي يتم فيها فقدان الإذن.

عمليات التجميع المتوافقة

تتوفّر القيم المجمّعة التالية لـ SleepSessionRecord:

إرشادات عامة

في ما يلي بعض إرشادات أفضل الممارسات حول كيفية التعامل مع جلسات النوم في 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",
                metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH))
            ),
        )
    )
}

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

جلسات النوم

يمكنك قراءة بيانات النوم أو كتابتها في Health Connect. يتم عرض بيانات النوم كجلسة، ويمكن تقسيمها إلى 8 مراحل نوم مختلفة:

  • ‫UNKNOWN: لم يتم تحديد ما إذا كان المستخدم نائمًا أو أنّ ذلك غير معروف.
  • ‫AWAKE: يكون المستخدم مستيقظًا خلال دورة النوم، وليس أثناء النهار.
  • ‫SLEEPING: وصف عام أو غير دقيق للنوم
  • ‫OUT_OF_BED: ينهض المستخدم من السرير في منتصف جلسة النوم.
  • ‫AWAKE_IN_BED: يشير إلى أنّ المستخدم مستيقظ في السرير.
  • ‫LIGHT: المستخدم في دورة نوم خفيف.
  • ‫DEEP: المستخدم في دورة نوم عميق.
  • ‫REM: المستخدم في دورة نوم حركة العين السريعة.

تمثّل هذه القيم نوع النوم الذي يحصل عليه المستخدم خلال نطاق زمني معيّن. تُعدّ كتابة مراحل النوم اختيارية، ولكن يُنصح بها إذا كانت متاحة.

كتابة بيانات جلسات النوم

يتكوّن نوع البيانات SleepSessionRecord من جزأين:

  1. الجلسة الإجمالية التي تشمل مدة النوم بالكامل
  2. مراحل فردية أثناء جلسة النوم، مثل النوم الخفيف أو النوم العميق

في ما يلي كيفية إدراج جلسة نوم بدون مراحل:

val zoneRules = ZoneId.systemDefault().rules

// Calculate the specific offset for both start and end times
val startOffset = zoneRules.getOffset(startTime)
val endOffset = zoneRules.getOffset(endTime)

SleepSessionRecord(
    title = "weekend sleep",
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = startOffset,
    endZoneOffset = endOffset,
    metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH))
)

في ما يلي كيفية إضافة مراحل تغطي فترة جلسة النوم بأكملها:

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

قراءة بيانات جلسة النوم

لكل جلسة نوم يتم عرضها، عليك التحقّق مما إذا كانت بيانات مراحل النوم متوفّرة أيضًا:

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
}

حذف جلسة نوم

في ما يلي كيفية حذف جلسة. في هذا المثال، استخدمنا جلسة نوم:

val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)