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

המדריך הזה תואם לגרסה 1.1.0-alpha12 של 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 כדי לעזור לוודא שקיימים במערכת האקולוגית מטא-נתונים שימושיים נוספים.

ציון שיטת ההקלטה

חובה לציין פרטים של מטא-נתונים בכל פעם שמופעל אובייקט מסוג 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.manualEntry(),
    Count = 10,
)

סוג המכשיר

חובה לציין סוג מכשיר לכל הנתונים שמתועדים באופן אוטומטי ופעיל. אפשר גם לציין את המאפיינים manufacturer ו-model, אבל הם אופציונליים. פרטים נוספים זמינים במאמר בנושא הכיתה 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
}
מידע נוסף זמין במאמר בדיקת הזמינות של תכונות.

אם אפשר, כדאי לציין את היצרן והדגם של המכשיר בנוסף לסוג המכשיר. לדוגמה:

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 וב-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 לא צפוי במכשירים שבהם התכונה לא זמינה.