متطلبات البيانات الوصفية

يتوافق هذا الدليل مع الإصدار ‎1.2.0-alpha05 من Health Connect والإصدارات الأحدث.

هناك تغييرات في البيانات الوصفية في Health Connect للمطوّرين الذين يرقّون إلى الإصدار 1.1.0-alpha12 أو إصدار أحدث.

معلومات المكتبة

يحدِّد معرّف العنصر المكوّن الإضافي لنظام Gradle المتوافق مع Android في مستودع Google Maven مكتبة Health Connect التي عليك ترقيتها. أضِف مصدر الاعتمادية الخاص بحزمة تطوير البرامج (SDK) لتطبيق Health Connect إلى ملف build.gradle على مستوى الوحدة:

dependencies {
  implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}

تغييرات البيانات الوصفية

تم إجراء تغييرَين على البيانات الوصفية في حزمة تطوير البرامج (SDK) لتطبيق Health Connect على Jetpack اعتبارًا من الإصدار ‎1.1.0-alpha12 للمساعدة في التأكّد من توفّر بيانات وصفية إضافية مفيدة في المنظومة المتكاملة. إذا لم يتم تضمين metadata في أداة الإنشاء Record، قد يظهر لك الخطأ Constructor internal.

تحديد طريقة التسجيل

يجب تحديد تفاصيل البيانات الوصفية كلما تم إنشاء مثيل لعنصر من النوع Record().

عند كتابة البيانات في Health Connect، يجب تحديد إحدى طرق التسجيل الأربع باستخدام إحدى طرق الإنشاء المناسبة لإنشاء مثيل من Metadata:

على سبيل المثال:

 StepsRecord(
    startTime = Instant.ofEpochMilli(1234L),
    startZoneOffset = null,
    endTime = Instant.ofEpochMilli(1236L),
    endZoneOffset = null,
    metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    count = 10
)
HealthConnectManager.kt

نوع الجهاز

يجب تحديد نوع الجهاز لجميع البيانات التي يتم تسجيلها تلقائيًا وبشكل نشط. لمزيد من التفاصيل، اطّلِع على فئة Device في مستندات Jetpack. تشمل أنواع الأجهزة الحالية ما يلي:

لا تتوفّر بعض قيم Device.type إلا في الإصدارات الأحدث من Health Connect. عندما لا تتوفّر ميزة "أنواع الأجهزة الإضافية"، يتم التعامل مع هذه الأنواع على أنّها Device.TYPE_UNKNOWN.

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_EXTENDED_DEVICE_TYPES
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

على سبيل المثال:

 val WATCH_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel Watch",
    type = Device.TYPE_WATCH
)

// Phone
 val PHONE_DEVICE = Device(
    manufacturer = "Google",
    model = "Pixel 8",
    type = Device.TYPE_PHONE
)

// Ring
 val RING_DEVICE = Device(
    manufacturer = "Oura",
    model = "Ring Gen3",
    type = Device.TYPE_RING
)

// Scale
 val SCALE_DEVICE = Device(
    manufacturer = "Withings",
    model = "Body Comp",
    type = Device.TYPE_SCALE
)
HealthConnectManager.kt

معرّف الجهاز الفريد (UDI)

في Health Connect على Android 17 (المستوى 37.1 من واجهة برمجة التطبيقات) أو الإصدار 23 من حزمة U أو الإصدارات الأحدث، تتضمّن الفئة Device إمكانية استخدام المعرّف الفريد للجهاز (UDI). إنّ ربط تفاصيل نموذج معرّف الجهاز الفريد (UDI) المسجّل الخاص بجهاز طبي بسجلّاتك المكتوبة يتيح للتطبيقات اللاحقة (مثل منصات الرعاية الصحية عن بُعد أو البوابات السريرية) تحديد القراءات السريرية وتمييزها عن البيانات العامة التي تجمعها الأجهزة القابلة للارتداء.

تضمين الإذن في نموذج البيان

لكتابة تفاصيل معرّف الجهاز الفريد (UDI) في Health Connect، يجب إدراج الإذن WRITE_DEVICE_UDI في ملف AndroidManifest.xml الخاص بتطبيقك:

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

يُرجى العِلم أنّ WRITE_DEVICE_UDI هو إذن عادي. يجب توضيح هذا الإذن في ملف البيان، ولكن ليس عليك طلبه من المستخدم أثناء التشغيل. ويتم منح هذا الإذن تلقائيًا لتطبيقك عند تثبيته.

اكتب جزء معرّف الجهاز (DI) فقط

يتضمّن المعرّف الفريد للأجهزة (UDI) الكامل جزأين:

• معرّف الجهاز (UDI-DI): هو معرّف معترف به عالميًا وتحدّده جهة إصدار (مثل GS1) لطراز جهاز معيّن.
• معرّف المنتج (UDI-PI): سمات خاصة بالوحدة، مثل الأرقام التسلسلية أو أرقام الدُفعات أو تواريخ التصنيع أو تواريخ انتهاء الصلاحية

لحماية خصوصية المستخدم، املأ فقط جزء UDI-DI من الرمز في Health Connect. لا تضمِّن أي سمات معرّف إنتاج (مثل الأرقام التسلسلية أو أرقام الدُفعات).

مثال للرمز

ملاحظة: يمكنك ضبط معرّف الجهاز الفريد عند إنشاء مثيل Device.

val device = Device(
    type = Device.TYPE_CONSUMER_MEDICAL_DEVICE,
    manufacturer = "Omron",
    model = "HEM-7121",
    udi = "04015674011832" // Device Identifier (UDI-DI) portion only
)

val device = Device.Builder()
    .setType(Device.DEVICE_TYPE_CONSUMER_MEDICAL_DEVICE)
    .setManufacturer("Omron")
    .setModel("HEM-7121")
    .setUdi("04015674011832") // Device Identifier (UDI-DI) portion only
    .build()

إذا كنت تكتب بيانات باستخدام معرّف جهاز فريد (UDI) بدون الإفصاح عن إذن WRITE_DEVICE_UDI، سيُظهر Health Connect الخطأ SecurityException عند الكتابة.

استخدام معرّف الجهاز الفريد للتحقّق من إذن الجهاز

يعمل Health Connect كطبقة نقل، وهو لا يتحقّق من صحة معرّف الجهاز الفريد أو حالة تسجيله.

بالنسبة إلى قارئات البيانات، يشير توفّر معرّف الجهاز الفريد إلى أنّ البيانات مصدرها جهاز طبي مسجّل. يجب أن تستعلم تطبيقات القراءة عن قواعد البيانات التنظيمية، مثل قاعدة بيانات نظام التعريف العالمي الفريد للأجهزة (GUDID) التابعة لإدارة الغذاء والدواء الأمريكية (FDA) أو قاعدة بيانات EUDAMED التابعة للاتحاد الأوروبي، وذلك للتحقّق من تصنيفات الأجهزة أو حالة الموافقة التنظيمية (مثل الفئة الأولى أو الثانية أو الثالثة) أو الاستخدامات المحدّدة المقصودة.

تم تعديل المقتطفات

تم تعديل أدلة Health Connect في أي مكان يلزم فيه إضافة مقتطفات جديدة للامتثال لمتطلبات البيانات الوصفية الجديدة. للاطّلاع على بعض الأمثلة، يُرجى الرجوع إلى صفحة كتابة البيانات.

طُرق جديدة للبيانات الوصفية

لم يعُد من الممكن إنشاء بيانات وصفية مباشرةً، لذا استخدِم إحدى طرق الإنشاء للحصول على نسخة جديدة من البيانات الوصفية. تتحقّق طرق المصنع من توفّر معلومات الجهاز عند استخدام جهاز أو مستشعر لتسجيل البيانات. بالنسبة إلى البيانات التي يتم إدخالها يدويًا، يظل تقديم معلومات الجهاز اختياريًا. تحتوي كل دالة على ثلاثة أشكال مختلفة للتوقيع:

• activelyRecorded

  • fun activelyRecorded(device: Device): Metadata.
  • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun activelyRecordedWithId(id: String, device: Device): Metadata

• autoRecorded

  • fun autoRecorded(device: Device): Metadata
  • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
  • fun autoRecordedWithId(id: String, device: Device): Metadata

• manualEntry

  • fun manualEntry(device: Device? = null): Metadata
  • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun manualEntryWithId(id: String, device: Device? = null): Metadata

• unknownRecordingMethod

  • fun unknownRecordingMethod(device: Device? = null): Metadata
  • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
  • fun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata

لمزيد من المعلومات، يُرجى الاطّلاع على مشروع مفتوح المصدر لنظام Android.

بيانات الاختبار

استخدِم Testing Library وMetadataTestHelper لمحاكاة قيم البيانات الوصفية المتوقّعة:

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

يحاكي ذلك سلوك عملية تنفيذ Health Connect، التي تملأ هذه القيم تلقائيًا أثناء إدراج السجلّ.

بالنسبة إلى مكتبة الاختبار، عليك إضافة ملحق حزمة تطوير البرامج (SDK) لتطبيق Health Connect إلى ملف build.gradle على مستوى الوحدة:

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

ترقية المكتبة

في ما يلي الخطوات الرئيسية التي عليك اتّخاذها:

1. يجب ترقية المكتبة إلى الإصدار 1.1.0-alpha12.

2. عند إنشاء المكتبة، سيتم عرض أخطاء في الترجمة حيث تكون هناك حاجة إلى بيانات وصفية جديدة. لحلّ هذه الأخطاء وإكمال عملية نقل البيانات، تأكَّد من إجراء التغييرات التالية:

   • يجب تحديد طريقة تسجيل عند إنشاء Record. يتم ذلك باستخدام إحدى طرق الإنشاء المتوفّرة في Metadata، مثل Metadata.manualEntry() أو Metadata.activelyRecorded(device = Device(...)).
   • بالنسبة إلى البيانات التي يسجّلها جهاز، يجب تحديد نوع الجهاز، مثل Device.TYPE_WATCH أو Device.TYPE_PHONE.

3. إذا كان تطبيقك يكتب أنواعًا موسّعة من الأجهزة، عليك إخفاء هذه الأنواع خلف FEATURE_EXTENTED_DEVICE_TYPES لتجنُّب حدوث TYPE_UNKNOWN غير متوقّع على الأجهزة التي لا تتوفّر عليها الميزة.