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

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha12 من Health Connect.

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

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

يحدِّد معرّف العنصر Android gradle plugin في 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 لضمان توفّر بيانات وصفية إضافية مفيدة في المنظومة المتكاملة.

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

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

يجب تحديد إحدى طرق التسجيل الأربع عند كتابة البيانات في Health Connect:

طريقة التسجيل الوصف
RECORDING_METHOD_UNKNOWN يتعذّر التحقّق من طريقة التسجيل.
RECORDING_METHOD_MANUAL_ENTRY أدخل المستخدم البيانات.
RECORDING_METHOD_AUTOMATICALLY_RECORDED تم تسجيل البيانات من خلال جهاز أو أداة استشعار.
RECORDING_METHOD_ACTIVELY_RECORDED بدأ المستخدم جلسة التسجيل أو أنهىها على أحد الأجهزة.

مثلاً:

StepsRecord(
    startTime \= Instant.ofEpochMilli(1234L),
    startZoneOffset \= null,
    endTime \= Instant.ofEpochMilli(1236L),
    endZoneOffset \= null,
    metadata \= Metadata.manualEntry(),
    Count \= 10,
)

نوع الجهاز

يجب تحديد نوع الجهاز لجميع البيانات التي يتم تسجيلها تلقائيًا وبشكل نشط. تشمل أنواع الأجهزة الحالية ما يلي:

نوع الجهاز الوصف
TYPE_UNKNOWN نوع الجهاز غير معروف.
TYPE_WATCH نوع الجهاز هو ساعة.
TYPE_PHONE نوع الجهاز هو هاتف.
TYPE_SCALE نوع الجهاز هو ميزان.
TYPE_RING نوع الجهاز هو خاتم.
TYPE_HEAD_MOUNTED نوع الجهاز هو جهاز يُثبّت على الرأس.
TYPE_FITNESS_BAND نوع الجهاز هو سوار تتبُّع اللياقة البدنية.
TYPE_CHEST_STRAP نوع الجهاز هو حزام صدر.
TYPE_SMART_DISPLAY نوع الجهاز هو شاشة ذكية.

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

أنواع الأجهزة الموسّعة الوصف
TYPE_CONSUMER_MEDICAL_DEVICE نوع الجهاز هو جهاز طبي.
TYPE_GLASSES نوع الجهاز هو نظارات ذكية أو نظارات.
TYPE_HEARABLE نوع الجهاز هو جهاز سمعي.
TYPE_FITNESS_MACHINE نوع الجهاز هو آلة ثابتة.
TYPE_FITNESS_EQUIPMENT نوع الجهاز هو معدّات لياقة بدنية.
TYPE_PORTABLE_COMPUTER نوع الجهاز هو كمبيوتر محمول.
TYPE_METER نوع الجهاز هو مقياس.
لتحديد ما إذا كان جهاز المستخدم يتيح استخدام أنواع الأجهزة الموسّعة في Health Connect، تحقَّق من توفُّر FEATURE_EXTENDED_DEVICE_TYPES على العميل باتّباع الخطوات التالية:

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

  // Feature is available
} else {
  // Feature isn't available
}
لمزيد من المعلومات، يُرجى الاطّلاع على التحقّق من توفّر الميزة.

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

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

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

تم تعديل أدلة 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 لمحاكاة قيم البيانات الوصفية المتوقّعة:

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(). من المفترض أن يؤدي ذلك إلى إكمال عملية نقل البيانات.

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