پیگیری جلسات خواب

این راهنما با Health Connect نسخه ۱.۱.۰-alpha۱۱ سازگار است.

Health Connect یک نوع داده‌ی جلسه‌ی خواب ارائه می‌دهد تا اطلاعات مربوط به خواب کاربر، مانند یک جلسه‌ی شبانه یا چرت روزانه، را ذخیره کند. نوع داده‌ی SleepSessionRecord برای نمایش این جلسات استفاده می‌شود.

جلسات به کاربران این امکان را می‌دهد که عملکرد مبتنی بر زمان را در یک دوره زمانی، مانند ضربان قلب مداوم یا داده‌های مکانی، اندازه‌گیری کنند.

جلسات SleepSessionRecord حاوی داده‌هایی هستند که مراحل خواب، مانند AWAKE ، SLEEPING و DEEP را ثبت می‌کنند.

داده‌های زیرنوع ، داده‌هایی هستند که به یک جلسه «متعلق» هستند و فقط زمانی معنی‌دار هستند که با یک جلسه والد خوانده شوند. برای مثال، مرحله خواب.

بررسی در دسترس بودن 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 شروع کنید.

برای نوشتن session خواب، باید مجوز زیر را اعلام کنید:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_SLEEP" />
...
</application>

برای خواندن جلسه خواب، باید مجوزهای زیر را درخواست کنید:

<application>
  <uses-permission
android:name="android.permission.health.READ_SLEEP" />
...
</application>

درخواست مجوز از کاربر

پس از ایجاد یک نمونه کلاینت، برنامه شما باید از کاربر درخواست مجوز کند. کاربران باید بتوانند در هر زمانی مجوزها را اعطا یا رد کنند.

برای انجام این کار، مجموعه‌ای از مجوزها را برای انواع داده‌های مورد نیاز ایجاد کنید. مطمئن شوید که مجوزهای موجود در مجموعه ابتدا در مانیفست اندروید شما تعریف شده‌اند.

// 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"
            ),
        )
    )
}
  • جلسات نباید برای اندازه‌گیری‌های کلی، مانند شمارش گام‌های روزانه، استفاده شوند.
  • داده‌های زیرنوع شامل UID نیستند، اما داده‌های مرتبط دارای UIDهای متمایزی هستند.
  • داده‌های زیرنوع باید در یک جلسه با مهرهای زمانی متوالی که همپوشانی ندارند، تراز شوند. با این حال، فاصله‌ها مجاز هستند.
  • جلسات در صورتی مفید هستند که کاربر بخواهد داده‌ها به یک جلسه مرتبط شوند (و به عنوان بخشی از آن ردیابی شوند)، نه اینکه به طور مداوم ثبت شوند.

جلسات خواب

شما می‌توانید داده‌های خواب را در Health Connect بخوانید یا بنویسید. داده‌های خواب به صورت یک جلسه نمایش داده می‌شوند و می‌توانند به ۸ مرحله خواب مجزا تقسیم شوند:

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

یک جلسه خواب بخوانید

برای هر جلسه خواب برگشتی، باید بررسی کنید که آیا داده‌های مرحله خواب نیز وجود دارد یا خیر:

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