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

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