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

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

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

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

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

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

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

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

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

قبل‌از شروع

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

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

مفاهیم اصلی

داده‌های علائم حیاتی در 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 به‌روز نگه دارید، از ChangeLogs استفاده کنید. این ویژگی به شما امکان می‌دهد فهرستی از رکوردهای درج‌شده، به‌روزشده، یا حذف‌شده را از یک نقطه زمانی خاص بازیابی کنید، که کارآمدتر از ردیابی دستی تغییرات یا خواندن مکرر همه داده‌ها است. برای اطلاعات بیشتر، به همگام‌سازی داده‌ها با 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: از کتابخانه آزمایشی برای درستی‌سنجی نحوه مدیریت موارد حاشیه‌ای توسط برنامه‌تان، مانند لغو اجازه یا استثناهای میانای برنامه‌سازی کاربردی، بدون نیاز به دستگاه فیزیکی استفاده کنید.

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

معماری معمول

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

عیب‌یابی

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