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

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

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

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

يحدّد معرّف العنصر Google Maven Android gradle plugin مكتبة 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، قد يظهر لك خطأ خطأ داخلي في دالة الإنشاء.

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

يجب تحديد تفاصيل البيانات الوصفية كلما تم إنشاء مثيل لعنصر من النوع 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-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.

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

استخدِم مكتبة الاختبار و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 غير متوقّع على الأجهزة التي لا تتوفّر فيها الميزة.