تطوير تجارب بيانات المؤشرات الحيوية باستخدام Health Connect

يتوافق هذا الدليل مع الإصدار 1.1.0 من 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 معالجة ما يصل إلى 1000 سجلّ في طلب كتابة واحد.

يوضّح الرمز التالي كيفية كتابة سجلّات متعددة دفعة واحدة:

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 واحد مع مجموعات تصل إلى 1000 سجلّ، بدلاً من كتابة كل نقطة على حدة.
• كتابة البيانات بشكل متكرّر أثناء التتبُّع المباشر: للحصول على تحديثات متكرّرة من أجهزة الاستشعار (مثل أجهزة المراقبة المستمرة للغلوكوز أو معدّل نبضات القلب)، اكتب البيانات على دفعات على فترات تصل إلى 15 دقيقة لتحقيق التوازن بين التحديثات في الوقت الفعلي وكفاءة البطارية.
• استخدام WorkManager لعمليات المزامنة في الخلفية: استخدِم WorkManager لعمليات الكتابة المؤجَّلة، مثل مزامنة البيانات من جهاز مصاحب أو خدمة خلفية. ننصحك بضبط فاصل زمني مدته 15 دقيقة لعمليات الكتابة المجمّعة.
• تجنُّب كتابة بيانات مكرّرة: استخدِم معرّفات العملاء: عند إنشاء السجلّات، اضبط 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 Toolbox: يمكنك استخدام هذا التطبيق المصاحب لفحص السجلات يدويًا وحذف بيانات الاختبار ومحاكاة التغييرات في قاعدة البيانات. إنها أفضل طريقة للتحقق من تخزين سجلاتك بشكل صحيح.
• اختبار الوحدات باستخدام FakeHealthConnectClient: استخدِم مكتبة الاختبار للتحقّق من كيفية تعامل تطبيقك مع الحالات الاستثنائية، مثل إلغاء الأذونات أو استثناءات واجهة برمجة التطبيقات بدون الحاجة إلى جهاز فعلي.

قائمة التحقّق من الجودة

البنية النموذجية

يتضمّن تنفيذ المؤشرات الحيوية عادةً ما يلي:

تحديد المشاكل وحلّها

الخطوات الشائعة لتصحيح الأخطاء