با Health Connect تجربیات Vitals را توسعه دهید

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

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

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

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

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

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

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

قبل از اینکه شروع کنی

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

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

مفاهیم کلیدی

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

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

داده‌های حیاتی توسط انواع رکوردهای جداگانه نمایش داده می‌شوند. انواع رایج عبارتند از:

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

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

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

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

مجوزها

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

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

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

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

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

// Create a set of permissions for required data types
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)
)

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

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

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

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

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

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

• 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 را شرح می‌دهد. داده‌های حیاتی معمولاً به صورت رکوردهای جداگانه نوشته می‌شوند. اگر چندین رکورد را همزمان می‌نویسید، مانند همگام‌سازی از یک حسگر یا backend، از دسته‌بندی استفاده کنید.

مثالی از نوشتن یک 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))
}

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

اگر برنامه شما نیاز به نوشتن چندین نقطه داده دارد، مانند همگام‌سازی داده‌ها از یک دستگاه متصل یا یک سرویس backend، باید نوشتن‌ها را به صورت دسته‌ای انجام دهید تا کارایی بهبود یابد و مصرف باتری کاهش یابد. 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 برای نوشتن‌های معوق، مانند همگام‌سازی داده‌ها از یک دستگاه همراه یا سرویس backend، استفاده کنید. برای نوشتن‌های دسته‌ای، یک فاصله زمانی ۱۵ دقیقه‌ای را در نظر بگیرید.

• از نوشتن داده‌های تکراری خودداری کنید: از شناسه‌های کلاینت استفاده کنید. هنگام ایجاد رکوردها، یک metadata.clientRecordId تنظیم کنید. Health Connect از این برای شناسایی رکوردهای منحصر به فرد استفاده می‌کند. اگر سعی کنید رکوردی را با clientRecordId موجود بنویسید، Health Connect به جای ایجاد یک رکورد جدید، رکورد تکراری را نادیده می‌گیرد یا رکورد موجود را به‌روزرسانی می‌کند. تنظیم metadata.clientRecordId موثرترین راه برای جلوگیری از تکرار در هنگام تلاش‌های مجدد همگام‌سازی یا نصب مجدد برنامه است.

  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,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "bp_20240101_user123"
      )
  )

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

• دلایل منطقی و واضحی برای مجوز ارائه دهید: از جریان Permission.createIntent برای توضیح اینکه چرا برنامه شما به دسترسی به داده‌های سلامت نیاز دارد، مانند «برای نظارت بر روند فشار خون شما و ارائه بینش» استفاده کنید.

• تطبیق مهرهای زمانی با اندازه‌گیری‌ها: بررسی کنید که مهرهای زمانی رکورد دقیقاً زمان انجام اندازه‌گیری‌ها را نشان دهند. برای داده‌های بازه زمانی مانند HeartRateRecord ، بررسی کنید که startTime و endTime صحیح باشند.

آزمایش

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

ابزارهای تأیید

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

چک لیست کیفیت

معماری معمولی

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

عیب‌یابی

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

• بررسی وضعیت مجوزها: همیشه قبل از اقدام به عملیات خواندن یا نوشتن، تابع getPermissionStatus() را فراخوانی کنید. کاربران می‌توانند در هر زمانی مجوزها را در تنظیمات سیستم لغو کنند.