توسعه «تجربه‌های علائم حیاتی» با Health Connect

اگر به‌دنبال ساختن برنامه‌ای هستید که علائم حیاتی کاربر را مدیریت کند، می‌توانید از Health Connect برای انجام کارهایی مثل موارد زیر استفاده کنید:

• خواندن داده‌های علائم حیاتی مثل فشار خون، ضربان قلب، و دمای بدن از برنامه‌های دیگر
• نوشتن داده‌های حیاتی ضبط‌شده توسط برنامه یا دستگاه‌های متصل
• پایش گرایش‌ها و ارائه اطلاعات آماری سلامتی براساس داده‌های علائم حیاتی

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

نمای کلی: ساختن ردیاب جامع علائم حیاتی

با دنبال کردن این مراحل اصلی می‌توانید تجربه جامعی از ردیابی علائم حیاتی بااستفاده از Health Connect بسازید:

• درخواست اجازه‌های مناسب برای انواع داده‌های حیاتی.
• نوشتن داده‌های حیاتی بااستفاده از سوابقی مثل BloodPressureRecord، HeartRateRecord، و دیگر سوابق حیاتی.
• درحال خواندن داده‌های علائم حیاتی برای نمایش، تجزیه‌وتحلیل، یا همگام‌سازی.
• استفاده از دسته‌بندی برای نوشتن و خواندن کارآمد داده‌ها.

این گردش کار امکان تعامل‌پذیری با سایر برنامه‌های Health Connect را فراهم می‌کند و دسترسی به داده‌های تحت کنترل کاربر را تأیید می‌کند.

قبل‌از شروع

قبل‌از پیاده‌سازی ویژگی‌های حیاتی:

• بااستفاده از وابستگی مناسب، Health Connect را یکپارچه کنید.
• یک نمونه HealthConnectClient ایجاد کنید.
• تأیید کنید که برنامه شما جریان‌های اجازه زمان اجرا را براساس «اجازه‌های سلامتی» پیاده‌سازی می‌کند.

مفاهیم اصلی

داده‌های علائم حیاتی در Health Connect با انواع مختلفی از سوابق نشان داده می‌شود که هرکدام با اندازه‌گیری فیزیولوژیکی خاصی مطابقت دارد. برخلاف جلسات تمرین، علائم حیاتی اغلب به‌عنوان داده‌های نقطه‌ای یا فاصله‌ای ثبت می‌شوند.

انواع داده‌های علائم حیاتی

داده‌های علائم حیاتی با انواع سوابق فردی نشان داده می‌شود. انواع رایج عبارت‌اند از:

• BloodPressureRecord: نشان‌دهنده یک خوانش فشار خون است، ازجمله فشار سیستولیک و دیاستولیک، و وضعیت بدن.
• HeartRateRecord: نشان‌دهنده مجموعه‌ای از اندازه‌گیری‌های ضربان قلب است.
• RestingHeartRateRecord: نشان‌دهنده یک اندازه‌گیری واحد از ضربان قلب در حالت استراحت است.
• BodyTemperatureRecord: نشان‌دهنده یک خوانش دمای بدن، شامل مکان اندازه‌گیری.
• BloodGlucoseRecord: نشان‌دهنده یک خوانش قند خون، شامل ارتباط با وعده غذایی و منبع نمونه.
• OxygenSaturationRecord: نشان‌دهنده یک خوانش اشباع اکسیژن خون است.
• RespiratoryRateRecord: نشان‌دهنده یک اندازه‌گیری سرعت تنفس است.

برای فهرست کامل انواع داده، انواع داده Health Connect را ببینید.

ملاحظات توسعه

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

اجازه‌ها

برنامه شما باید قبل‌از خواندن یا نوشتن داده‌های حیاتی، اجازه‌های مربوط به Health Connect را درخواست کند. اجازه‌های رایج برای علائم حیاتی شامل فشار خون، ضربان قلب، دمای بدن، قند خون، اشباع اکسیژن، و سرعت تنفس است. این شامل موارد زیر می‌شود:

• فشار خون: اجازه‌های خواندن و نوشتن برای BloodPressureRecord.
• ضربان قلب: اجازه‌های خواندن و نوشتن برای HeartRateRecord.
• ضربان قلب حین استراحت: اجازه‌های خواندن و نوشتن برای RestingHeartRateRecord.
• دمای بدن: اجازه‌های خواندن و نوشتن برای BodyTemperatureRecord.
• قند خون: اجازه‌های خواندن و نوشتن برای BloodGlucoseRecord.
• اشباع اکسیژن: اجازه‌های خواندن و نوشتن برای OxygenSaturationRecord.
• سرعت تنفس: اجازه‌های خواندن و نوشتن برای RespiratoryRateRecord.

در زیر نمونه‌ای از نحوه درخواست اجازه برای فشار خون، ضربان قلب، و دمای بدن نشان داده شده است:

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(BloodPressureRecord::class),
        HealthPermission.getWritePermission(BloodPressureRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(BodyTemperatureRecord::class),
        HealthPermission.getWritePermission(BodyTemperatureRecord::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

برای درخواست اجازه، تابع checkPermissionsAndRun را فراخوانی کنید:

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

اگر فقط باید برای یک نوع داده، مثلاً فشار خون، اجازه درخواست کنید، فقط آن نوع داده را در مجموعه اجازه‌هایتان بگنجانید:

دسترسی به فشار خون با اجازه‌های زیر محافظت می‌شود:

• android.permission.health.READ_BLOOD_PRESSURE
• android.permission.health.WRITE_BLOOD_PRESSURE

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

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

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

برای خواندن فشار خون، باید اجازه‌های زیر را درخواست کنید:

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

نوشتن داده‌های حیاتی

این بخش نحوه نوشتن داده‌های حیاتی در Health Connect را توضیح می‌دهد. داده‌های حیاتی معمولاً به‌صورت سوابق جداگانه نوشته می‌شود. اگر درحال نوشتن چندین گزارش به‌طور هم‌زمان هستید، مثلاً همگام‌سازی از حسگر یا زیرینه، از دسته‌بندی استفاده کنید.

نمونه نوشتن BloodPressureRecord:

suspend fun writeBloodPressureRecord(healthConnectClient: HealthConnectClient) {
    val record = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    healthConnectClient.insertRecords(listOf(record))
}

نوشتن گروهی

اگر برنامه شما نیاز دارد چندین نقطه داده را بنویسد، مثلاً داده‌ها را از دستگاه متصل یا سرویس زیرینه همگام‌سازی کند، باید نوشتارها را دسته‌ای کنید تا کارایی بهبود یابد و مصرف باتری کاهش یابد. ‫Health Connect می‌تواند تا ۱۰۰۰ سابقه را در یک درخواست نوشتن مدیریت کند.

کد زیر نشان می‌دهد که چگونه چندین گزارش را به‌صورت دسته‌ای و هم‌زمان بنویسید:

suspend fun writeBatchRecords(healthConnectClient: HealthConnectClient) {
    val bloodPressureRecord = BloodPressureRecord(
        time = Instant.now(),
        zoneOffset = ZoneOffset.UTC,
        systolic = Pressure.millimetersOfMercury(120.0),
        diastolic = Pressure.millimetersOfMercury(80.0),
        bodyPosition = BloodPressureRecord.BODY_POSITION_SITTING_DOWN,
        measurementLocation = BloodPressureRecord.MEASUREMENT_LOCATION_LEFT_WRIST
    )
    val heartRateRecord = HeartRateRecord(
        startTime = Instant.now().minusSeconds(60),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        samples = listOf(HeartRateRecord.Sample(time = Instant.now().minusSeconds(30), beatsPerMinute = 80))
    )
    healthConnectClient.insertRecords(listOf(bloodPressureRecord, heartRateRecord))
}

درحال خواندن داده‌های حیاتی

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

نمونه‌ای از خواندن داده‌های BloodPressureRecord:

suspend fun readBloodPressureRecords(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = BloodPressureRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (record in response.records) {
        // Process each blood pressure record
        val systolic = record.systolic
        val diastolic = record.diastolic
    }
}

اگر نیاز دارید داده‌های علائم حیاتی را با سرور پشتیبان همگام‌سازی کنید یا مخزن داده برنامه خود را با Health Connect به‌روز نگه دارید، از «گزارش‌های تغییر» استفاده کنید. این قابلیت به شما امکان می‌دهد فهرستی از سوابق درج‌شده، به‌روزشده، یا حذف‌شده را از زمان مشخصی بازیابی کنید که کارآمدتر از پیگیری دستی تغییرات یا خواندن مکرر همه داده‌ها است. برای اطلاعات بیشتر، به همگام‌سازی داده‌ها با Health Connect مراجعه کنید.

روال‌های مطلوب

برای بهبود قابلیت اطمینان داده‌ها و تجربه کاربری، این رهنمودها را دنبال کنید:

• درخواست‌های نوشتن دسته‌ای: برای کاهش سربار ورودی/خروجی و حفظ عمر باتری، نقاط داده را در یک فراخوانی insertRecords با دسته‌های حداکثر ۱۰۰۰ سابقه گروه‌بندی کنید، به‌جای اینکه هر نقطه را به‌صورت جداگانه بنویسید.
• نوشتن مکرر درطول ردیابی زنده: برای به‌روزرسانی‌های مکرر از حسگرها (مثل پایشگرهای مداوم گلوکز یا پایشگرهای ضربان قلب)، داده‌ها را در دسته‌هایی با فواصل حداکثر ۱۵ دقیقه بنویسید تا بین به‌روزرسانی‌های هم‌زمان و کارایی باتری تعادل برقرار شود.
• استفاده از WorkManager برای همگام‌سازی‌های پس‌زمینه: از WorkManager برای نوشتن‌های به‌تعویق‌افتاده، مثل همگام‌سازی داده‌ها از دستگاه همراه یا سرویس زیرینه، استفاده کنید. برای نوشتن دسته‌ای، فاصله زمانی ۱۵ دقیقه‌ای را هدف قرار دهید.
• از نوشتن داده‌های تکراری خودداری کنید: از «شناسه‌های مشتری» استفاده کنید: هنگام ایجاد سوابق، metadata.clientRecordId را تنظیم کنید. ‫Health Connect از این برای شناسایی سوابق منحصربه‌فرد استفاده می‌کند. اگر سعی کنید گزارشی با clientRecordId که ازقبل وجود دارد بنویسید، Health Connect از تکراری بودن آن چشم‌پوشی می‌کند یا گزارش موجود را به‌روز می‌کند و گزارش جدیدی ایجاد نمی‌کند. تنظیم metadata.clientRecordId مؤثرترین راه برای جلوگیری از موارد تکراری درطول تلاش‌های مجدد همگام‌سازی یا بازنصب برنامه است.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• بررسی داده‌های موجود: قبل‌از همگام‌سازی داده‌ها، Health Connect را برای سوابق در محدوده زمانی همگام‌سازی پُرسمان کنید تا ببینید آیا داده‌های برنامه شما ازقبل وجود دارد یا نه، تا از داده‌های تکراری یا بازنویسی داده‌های جدیدتر جلوگیری کنید.
• دلیل‌های واضح برای اجازه ارائه دهید: از جریان Permission.createIntent برای توضیح اینکه چرا برنامه‌تان به داده‌های سلامتی نیاز دارد استفاده کنید، برای مثال: «برای نظارت بر روند فشار خون شما و ارائه اطلاعات آماری.»
• تراز کردن مُهر زمان‌ها با اندازه‌گیری‌ها: تأیید کنید که مُهر زمان‌های سوابق به‌درستی زمان انجام اندازه‌گیری‌ها را منعکس می‌کنند. برای داده‌های بازه‌ای مثل HeartRateRecord، بررسی کنید startTime و endTime درست باشند.

آزمایش

برای تأیید صحت داده‌ها و تجربه کاربری با کیفیت بالا، این استراتژی‌های آزمایش را دنبال کنید و به اسناد رسمی آزمایش موارد استفاده برتر مراجعه کنید.

ابزارهای درستی‌سنجی

• جعبه‌ابزار Health Connect: از این برنامه همراه برای بازرسی دستی سوابق، حذف داده‌های آزمایشی، و شبیه‌سازی تغییرات در پایگاه داده استفاده کنید. این بهترین راه برای تأیید این است که سوابق شما به‌درستی ذخیره می‌شوند.
• آزمایش واحد با FakeHealthConnectClient: از کتابخانه آزمایش استفاده کنید تا بدون نیاز به دستگاه فیزیکی، نحوه مدیریت موارد حاشیه‌ای مانند لغو اجازه یا استثناهای API را در برنامه‌تان درستی‌سنجی کنید.

بازبینه کیفیت

معماری معمول

پیاده‌سازی علائم حیاتی معمولاً شامل موارد زیر است:

عیب‌یابی

مراحل رایج اشکال‌زدایی