הדרישות לגבי מטא-נתונים

המדריך הזה תואם לגרסה 1.2.0-alpha05 של Health Connect ולגרסאות מתקדמות יותר.

יש שינויים במטא-נתונים ב-Health Connect למפתחים שמשדרגים לגרסה 1.1.0-alpha12 ואילך.

פרטי הספרייה

מזהה הארטיפקט של הפלאגין של Google Maven Android gradle מציין את ספריית Health Connect שאליה תצטרכו לשדרג. מוסיפים את התלות הזו ב-Health Connect SDK לקובץ build.gradle ברמת המודול:

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

שינויים במטא-נתונים

החל מגרסה 1.1.0-alpha12 של Health Connect Jetpack SDK, נוספו שני שינויים במטא-נתונים כדי לאמת שקיימים במערכת האקולוגית מטא-נתונים שימושיים נוספים. אם 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 (רמת API‏ 37.1) או בתוסף U מגרסה 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 מלא מכיל שני חלקים:

• מזהה מכשיר (UDI-DI): מזהה מוכר בעולם שמוקצה לדגם מכשיר ספציפי על ידי סוכנות מנפיקה (לדוגמה, GS1).
• מזהה ייצור (UDI-PI): מאפיינים ספציפיים ליחידה, כמו מספרים סידוריים, מספרי אצווה, תאריכי ייצור או תאריכי תפוגה.

כדי להגן על פרטיות המשתמשים, מאכלסים רק את החלק של UDI-DI בקוד ב-Health Connect. אל תכללו מאפיינים של מזהי ייצור (כמו מספרים סידוריים או מספרי אצווה).

קוד לדוגמה

הערה: אפשר להגדיר את ה-UDI כשיוצרים מופע של 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 בזמן הכתיבה.

שימוש ב-UDI כדי לאמת את אישור המכשיר

‫Health Connect משמש כשכבת תעבורה ולא מאמת את האותנטיות או את סטטוס הרישום של ה-UDI.

לגבי קוראי נתונים, נוכחות של UDI מציינת שהנתונים מגיעים ממכשיר רפואי רשום. אפליקציות קריאה צריכות לשלוח שאילתות למאגרי מידע רגולטוריים כמו מאגר הנתונים העולמי של ה-FDA לזיהוי מכשירים ייחודיים (GUDID) או EUDAMED של האיחוד האירופי כדי לאמת סיווגי מכשירים, סטטוס אישור רגולטורי (לדוגמה, Class 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 לא צפוי במכשירים שבהם התכונה לא זמינה.