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

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

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

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

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

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

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

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

قبل محاولة استخدام Health Connect، يجب أن يتأكّد تطبيقك من توفُّر Health Connect على جهاز المستخدم. قد لا يكون تطبيق Health Connect مثبَّتًا مسبقًا على جميع الأجهزة أو قد يكون غير مفعَّل. يمكنك التحقّق من توفّره باستخدام طريقة 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()، يمكنك توجيه المستخدم لتثبيت تطبيق 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)
    )
HealthConnectManager.kt

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.") }
    }
}
HealthConnectActivity.kt

عمليات التجميع المتاحة

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

• SLEEP_DURATION_TOTAL

إرشادات عامة

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

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

جلسات النوم

يمكنك قراءة بيانات النوم أو كتابتها في 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,
)
HealthConnectManager.kt

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

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
}
HealthConnectManager.kt

حذف جلسة نوم

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

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