الزامات فراداده

این راهنما با Health Connect نسخه 1.2.0-alpha05 یا بالاتر سازگار است.

برای توسعه‌دهندگانی که به نسخه 1.1.0-alpha12 یا جدیدتر ارتقا می‌دهند، تغییراتی در فراداده Health Connect ایجاد شده است.

اطلاعات کتابخانه

شناسه محصول افزایه Google Maven Android gradle کتابخانه Health Connect را که باید به آن ارتقا دهید شناسایی می‌کند. این وابستگی Health Connect SDK را به فایل build.gradle سطح واحدتان اضافه کنید:

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

تغییرات فراداده

دو تغییر فراداده در Health Connect Jetpack SDK از نسخه 1.1.0-alpha12 معرفی شده است تا به تأیید وجود فراداده مفید تکمیلی در بوم‌سازگان کمک کند. اگر metadata در سازنده Record شما گنجانده نشده باشد، ممکن است خطای داخلی سازنده را ببینید.

مشخص کردن روش ضبط

هرگاه شیء نوع Record() نمونه‌سازی می‌شود، باید جزئیات فراداده را مشخص کنید.

هنگام نوشتن داده‌ها در Health Connect، باید یکی از چهار روش ضبط را بااستفاده از یکی از روش‌های کارخانه‌ای مربوطه برای نمونه‌سازی Metadata مشخص کنید:

روش ضبط شرح
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.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    count = 10
)

نوع دستگاه

باید نوع دستگاه را برای همه داده‌های ضبط‌شده به‌طور خودکار و فعال مشخص کنید. برای جزئیات بیشتر، کلاس Device را در اسناد Jetpack ببینید. انواع دستگاه‌های فعلی عبارت‌اند از:

نوع دستگاه شرح
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
}
برای کسب اطلاعات بیشتر، به بررسی دردسترس بودن ویژگی مراجعه کنید.

برای مثال:

 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
)

شناسه یکتای دستگاه (UDI)

برای Health Connect در Android 17 (سطح میانای برنامه‌سازی کاربردی ۳۷.۱) یا افزونه U نسخه ۲۳ یا بالاتر، کلاس Device شامل پشتیبانی از «شناسه یکتای دستگاه» (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 وارد کنید. هیچ‌گونه مشخصه شناسه تولید (مانند شماره سریال یا شماره دسته) را اضافه نکنید.

نمونه کد

توجه: می‌توانید UDI را هنگام ساختن نمونه Device تنظیم کنید.

Jetpack SDK

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

Platform API

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()

اگر داده‌ها را با «شناسه یکتای دستگاه» بدون اعلام اجازه WRITE_DEVICE_UDI بنویسید، Health Connect در زمان نوشتن SecurityException را نشان می‌دهد.

استفاده از شناسه دستگاه منحصربه‌فرد برای تأیید مجوز دستگاه

Health Connect به‌عنوان لایه انتقال عمل می‌کند و اصالت یا وضعیت ثبت UDI را اعتبارسنجی نمی‌کند.

برای خوانندگان داده، وجود «شناسه یکتای دستگاه» نشان می‌دهد که داده‌ها از یک دستگاه پزشکی ثبت‌شده منشأ می‌گیرند. برنامه‌های خواندن باید پایگاه‌های داده نظارتی مانند «پایگاه داده جهانی شناسایی منحصربه‌فرد دستگاه» (GUDID) متعلق به FDA یا EUDAMED متعلق به اتحادیه اروپا را جستجو کنند تا طبقه‌بندی‌های دستگاه، وضعیت مجوز نظارتی (برای مثال، کلاس I،‏ II، یا III)، یا کاربرد خاص موردنظر را تأیید کنند.

گزیده‌ها به‌روز شد

راهنماهای 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 را شبیه‌سازی می‌کند، که به‌طور خودکار این مقادیر را درطول درج سابقه پر می‌کند.

برای کتابخانه آزمایشی، باید این وابستگی Health Connect SDK را به فایل 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 غیرمنتظره در دستگاه‌هایی که این ویژگی دردسترس نیست جلوگیری شود.

قبلی
همگام سازی داده ها
بعدی
محدودیت های نرخ