از سال 2026، ما از APIهای Google Fit دور خواهیم شد. برای اطلاعات بیشتر در مورد انتقال Google Fit، به راهنمای مهاجرت مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

این راهنما با Health Connect نسخه 1.1.0-alpha11 سازگار است.

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

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

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

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

<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 موجود است:

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

جلسات نباید برای اندازه گیری های عمومی مانند شمارش گام های روزانه استفاده شوند.
داده‌های نوع فرعی حاوی یک UID نیستند، اما داده‌های مرتبط دارای UIDهای متمایز هستند.
داده‌های نوع فرعی باید در یک جلسه با مهرهای زمانی متوالی که همپوشانی ندارند، تراز شوند. با این حال، شکاف ها مجاز هستند.
جلسات زمانی مفید هستند که کاربر بخواهد به جای ضبط مداوم، داده ها با یک جلسه مرتبط شوند (و به عنوان بخشی از آن ردیابی شوند).

جلسات خواب

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

UNKNOWN : نامشخص یا ناشناخته اگر کاربر در خواب است.
AWAKE : کاربر در یک چرخه خواب بیدار است، نه در طول روز.
SLEEPING : توصیف خواب عمومی یا غیر دانه ای.
OUT_OF_BED : کاربر در وسط یک جلسه خواب از رختخواب خارج می شود.
AWAKE_IN_BED : کاربر در رختخواب بیدار است.
LIGHT : کاربر در یک چرخه خواب سبک است.
DEEP : کاربر در یک چرخه خواب عمیق است.
REM : کاربر در یک چرخه خواب REM است.

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

جلسات خواب را بنویسید

نوع داده SleepSessionRecord دو بخش دارد:

جلسه کلی که کل مدت خواب را در بر می گیرد.
مراحل فردی در طول جلسه خواب مانند خواب سبک یا خواب عمیق.

در اینجا نحوه قرار دادن یک جلسه خواب بدون مراحل آمده است:

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