تطوير تجارب بيانات المؤشرات الحيوية باستخدام 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.

// 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. عادةً ما يتم تسجيل بيانات المؤشرات الحيوية كسجلات فردية. إذا كنت تكتب سجلات متعددة في المرة الواحدة، مثل المزامنة من جهاز استشعار أو خادم خلفي، استخدِم التجميع.

مثال على كتابة 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 معالجة ما يصل إلى 1,000 سجلّ في طلب كتابة واحد.

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

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

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

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

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

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

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