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

این راهنما با Health Connect نسخه 1.2.0-alpha05 و نسخه‌های جدیدتر سازگار است.

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

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

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

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

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

از نسخه 1.1.0-alpha12، دو تغییر فراداده به کیت توسعه نرم‌افزار Health Connect Jetpack معرفی شده است تا به تأیید وجود فراداده مفید اضافی در اکوسیستم کمک کند. اگر 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 extension 23 یا نسخه‌های جدیدتر، کلاس 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 می‌توانید UDI را تنظیم کنید.

کیت توسعه نرم‌افزار Jetpack

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

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

از UDI برای تأیید مجوز دستگاه استفاده کنید

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

برای خوانندگان داده، وجود «شناسه یکتا» نشان می‌دهد که داده‌ها از یک دستگاه پزشکی ثبت‌شده منشأ می‌گیرد. برنامه‌های خواندن باید پایگاه‌های داده نظارتی مثل «پایگاه داده جهانی شناسایی دستگاه یکتا» (GUDID) متعلق به «سازمان غذا و دارو» یا 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 را ببینید.

درحال آزمایش داده‌ها

از کتابخانه آزمایش و MetadataTestHelper برای شبیه‌سازی مقادیر فراداده موردانتظار استفاده کنید:

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

این کار عملکرد پیاده‌سازی Health Connect را شبیه‌سازی می‌کند، که این مقادیر را درطول درج کردن سوابق به‌طور خودکار پر می‌کند.

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

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