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

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha11 من 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" // 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 manifest أولاً.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(SleepSessionRecord::class),
  HealthPermission.getWritePermission(SleepSessionRecord::class)
)

استخدِم getGrantedPermissions لمعرفة ما إذا كان تطبيقك قد حصل على الأذونات المطلوبة. إذا لم يكن الأمر كذلك، استخدِم createRequestPermissionResultContract لطلب هذه الأذونات. سيؤدي ذلك إلى عرض شاشة أذونات Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

بما أنّه يمكن للمستخدمين منح الأذونات أو إبطالها في أي وقت، على تطبيقك التحقّق من الأذونات في كل مرة قبل استخدامها والتعامل مع السيناريوهات التي يتم فيها فقدان الإذن.

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

تتوفّر القيم المجمّعة التالية لـ 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"
            ),
        )
    )
}

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

جلسات النوم

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

  • UNKNOWN: غير محدّد أو غير معروف ما إذا كان المستخدم نائمًا.
  • AWAKE: يكون المستخدم مستيقظًا خلال دورة النوم، وليس خلال النهار.
  • SLEEPING: وصف عام أو غير دقيق للنوم.
  • OUT_OF_BED: يخرج المستخدم من السرير في منتصف جلسة النوم.
  • AWAKE_IN_BED: يكون المستخدم مستيقظًا في السرير.
  • LIGHT: يكون المستخدم في دورة نوم خفيف.
  • DEEP: يكون المستخدم في دورة نوم عميق.
  • REM: يكون المستخدم في دورة نوم حركة العين السريعة (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,
)

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

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

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)