סנכרון נתונים

לרוב האפליקציות שמשתלבות עם Health Connect יש מאגר נתונים משלהם שמשמש כמקור האמיתי. אפליקציית Health Connect מספקת דרכים לשמירה על סנכרון האפליקציה.

חשוב לוודא שהאפליקציה עומדת בדרישות הבאות:

  • מעביר נתונים חדשים או מעודכנים ממאגר הנתונים של האפליקציה ל-Health Connect.
  • משיכת שינויים בנתונים מ-Health Connect, שמשתקפים במאגר הנתונים של האפליקציה.
  • מחיקה של נתונים מ-Health Connect כשהם נמחקים במאגר הנתונים של האפליקציה.

בכל מקרה, חשוב לוודא שתהליך הסנכרון שומר על התאמה בין Health Connect לבין מאגר הנתונים של האפליקציה.

איך מעבירים נתונים ל-Health Connect

החלק הראשון בתהליך הסנכרון הוא להזין נתונים מאחסון הנתונים של האפליקציה למאגר הנתונים של Health Connect.

הכנת הנתונים

בדרך כלל, הרשומות במאגר הנתונים של האפליקציה מכילות את הפרטים הבאים:

  • מפתח ייחודי, כמו UUID.
  • גרסה או חותמת זמן.

תכנון של מאגר הנתונים של האפליקציה כדי לעקוב אחרי הנתונים שכבר הוזנו ל-Health Connect. כדי לעשות זאת, צריך להשתמש בלוגיקה הבאה:

  • יש לספק רשימה של שינויים וטוקן שאפשר להשתמש בו כדי לאחזר רשומות עם עדכונים מאז שהונפק הטוקן האחרון.
  • מעקב אחרי הפעם האחרונה שבה הנתונים המיוצאים שונו.

השלבים האלה חיוניים כדי לוודא שרק נתונים חדשים או מעודכנים יישלחו ל-Health Connect.

כתיבת נתונים ב-Health Connect

כדי להזין נתונים ל-Health Connect, מבצעים את השלבים הבאים:

  1. הצגת רשימה של רשומות חדשות או מעודכנות מאחסון הנתונים של האפליקציה.
  2. לכל רשומה, יוצרים אובייקט Record שמתאים לסוג הנתונים הזה. לדוגמה, יוצרים אובייקט WeightRecord לנתונים שקשורים למשקל.

  3. מציינים אובייקט Metadata עם כל Record באמצעות המפתח הייחודי ופרטי הגרסה מאחסון הנתונים של האפליקציה. אם הנתונים לא מחולקים לגרסאות, אפשר להשתמש בערך Long של חותמת הזמן הנוכחית כחלופה.

    val record = WeightRecord(
    metadata = Metadata(
        clientRecordId = "<Your record's Client ID>",
        clientRecordVersion = <Your record's version>
    ),
    weight = weight,
    time = time,
    zoneOffset = zoneOffset
)

  4. הוספה או עדכון נתונים ב-Health Connect באמצעות insertRecords. הוספה או עדכון של נתונים (upsert) פירושה שכל הנתונים הקיימים ב-Health Connect יימחקו, כל עוד ערכי clientRecordId קיימים במאגר הנתונים של Health Connect והערך של clientRecordVersion גבוה מהערך הקיים. אחרת, הנתונים שמוסיפים נכתבים כנתונים חדשים.

    healthConnectClient.insertRecords(arrayListOf(record))

במאמר כתיבת נתונים מפורטות שיטות מומלצות לשימוש מעשי בפיד נתונים.

אחסון מזהי Health Connect

אחרי שמעדכנים את הרשומות ב-Health Connect, מאגר הנתונים של האפליקציה צריך לאחסן את הערך id של Health Connect לכל רשומה. כך האפליקציה יכולה לבדוק אם כל שינוי נכנס מחייב ליצור רשומה חדשה או לעדכן רשומה קיימת, אחרי שאתם שולפים את הנתונים.

הפונקציה insertRecords מחזירה את הערך InsertRecordsResponse שמכיל את רשימת הערכים של id. משתמשים בתגובה כדי לקבל את מזהי הרשומות ולאחסן אותם.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

אחזור נתונים מ-Health Connect

החלק השני בתהליך הסנכרון הוא אחזור של שינויים בנתונים מ-Health Connect למאגר הנתונים של האפליקציה. השינויים בנתונים יכולים לכלול עדכונים ומחיקה.

קבלת אסימון Changes

כדי לקבל רשימה של שינויים שאפשר למשוך מ-Health Connect, האפליקציה צריכה לעקוב אחרי אסימוני Changes. אפשר להשתמש בהם כששולחים בקשה ל-Changes כדי לקבל גם רשימה של שינויים בנתונים וגם אסימון Changes חדש לשימוש בפעם הבאה.

כדי לקבל אסימון Changes, צריך להפעיל את getChangesToken ולציין את סוגי הנתונים הנדרשים.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

בדיקה של שינויים בנתונים

עכשיו, אחרי שקיבלתם אסימון Changes, תוכלו להשתמש בו כדי לקבל את כל Changes. מומלץ ליצור לולאה כדי לעבור על כל השינויים ולבדוק אם יש שינויים זמינים בנתונים. אלה השלבים:

  1. קוראים ל-getChanges באמצעות האסימון כדי לקבל רשימה של שינויים.
  2. בודקים את כל שינוי כדי לבדוק אם הוא שינוי מסוג UpsertionChange או DeletionChange, ומבצעים את הפעולות הנדרשות.
    • בשדה UpsertionChange, צריך לכלול רק שינויים שלא הגיעו מאפליקציית הקריאה, כדי לוודא שלא מייבאים מחדש נתונים.
  3. מקצים את האסימון הבא מסוג Changes כאסימון החדש.
  4. חוזרים על שלבים 1 עד 3 עד שלא נשארים שינויים.
  5. שומרים את האסימון הבא ומשמרים אותו לייבוא עתידי.
suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

כדי לקבל מידע על השיקולים המעשיים של משיכת נתונים, כדאי לעיין בשיטות המומלצות לסנכרון נתונים.

עיבוד שינויים בנתונים

משקפים את השינויים במאגר הנתונים של האפליקציה. עבור UpsertionChange, משתמשים ב-id וב-lastModifiedTime מ-metadata כדי להוסיף או לעדכן את הרשומה. עבור DeletionChange, משתמשים ב-id שסופק כדי למחוק את הרשומה.

מחיקת נתונים מ-Health Connect

כשמשתמש מחק את הנתונים שלו מהאפליקציה, חשוב לוודא שהנתונים הוסר גם מ-Health Connect. כדי לעשות זאת, משתמשים בפקודה deleteRecords. הפונקציה מקבלת סוג רשומה ורשימה של ערכים של id ו-clientRecordId, כך שקל למחוק כמה נתונים בבת אחת. יש גם אפשרות חלופית deleteRecords שמקבלת timeRangeFilter.

שיטות מומלצות לסנכרון נתונים

הגורמים הבאים משפיעים על תהליך הסנכרון.

תפוגת תוקף של אסימון

מכיוון שפג התוקף של אסימון Changes שלא נעשה בו שימוש תוך 30 יום, צריך להשתמש באסטרטגיית סנכרון שמונעת אובדן מידע במקרה כזה. האסטרטגיה שלכם יכולה לכלול את הגישות הבאות:

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

אסטרטגיות מומלצות לניהול שינויים

אם האפליקציה שלכם מקבלת אסימוני Changes לא חוקיים או שפג תוקפם, מומלץ להשתמש באסטרטגיות הניהול הבאות בהתאם לאופן שבו האסימונים מוטמעים בלוגיקה שלכם:

  • קריאה של כל הנתונים והסרת כפילויות זוהי האסטרטגיה האידיאלית ביותר.
    • לאחסן את חותמת הזמן של הפעם האחרונה שהן קראו נתונים מ-Health Connect.
    • בתום התוקף של האסימון, צריך לקרוא מחדש את כל הנתונים מחותמת הזמן האחרונה או מ-30 הימים האחרונים. לאחר מכן, מסירים כפילויות באמצעות מזהים בהשוואה לנתונים שקראתם קודם.
    • מומלץ להטמיע מזהי לקוח כי הם נדרשים לעדכוני נתונים.
  • קריאת נתונים רק מחותמת הזמן האחרונה לקריאה. כתוצאה מכך, יכולות להיות אי-התאמות מסוימות בנתונים סביב מועד התפוגה של אסימון השינויים, אבל פרק הזמן קצר יותר ויכול להימשך כמה שעות עד כמה ימים.
    • לאחסן את חותמת הזמן של הפעם האחרונה שהן קראו נתונים מ-Health Connect.
    • בתום התוקף של האסימון, קוראים את כל הנתונים החל מחותמת הזמן הזו ואילך.
  • מחיקת הנתונים מ-30 הימים האחרונים ואז קריאת הנתונים. כך אפשר לקבל תמונה מדויקת יותר של מה שקורה בשילוב הראשון.
    • למחוק את כל הנתונים שהאפליקציה קראה מ-Health Connect ב-30 הימים האחרונים.
    • אחרי המחיקה, צריך לקרוא שוב את כל הנתונים האלה.
  • קריאת נתונים מ-30 הימים האחרונים ללא מחיקה כפולה. זוהי השיטה הכי פחות אידיאלית, והיא גורמת להצגת נתונים כפולים למשתמשים.
    • למחוק את כל הנתונים שהאפליקציה קראה מ-Health Connect ב-30 הימים האחרונים.
    • לאפשר כניסות כפולות.

אסימונים של שינויים בסוג הנתונים

אם האפליקציה שלכם צורכת יותר מסוג נתונים אחד בנפרד, צריך להשתמש באסימוני Changes נפרדים לכל סוג נתונים. מומלץ להשתמש ברשימת סוגי נתונים מרובים ב-Changes Sync API רק אם סוגי הנתונים האלה נצרכים יחד או לא נצרכים בכלל.

קריאות בחזית

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

קריאה ברקע

אתם יכולים לבקש שהאפליקציה תפעל ברקע ותוכל לקרוא נתונים מ-Health Connect. אם מבקשים את ההרשאה Background Read, המשתמש יכול להעניק לאפליקציה גישה לקריאת נתונים ברקע.

ייבוא תזמונים

מכיוון שאין לאפליקציה אפשרות לקבל התראות על נתונים חדשים, צריך לבדוק אם יש נתונים חדשים בשני רגעים:

  • בכל פעם שהאפליקציה שלכם הופכת לפעילה בחזית. במקרה כזה, צריך להשתמש באירועים במחזור החיים.
  • מדי פעם, כשהאפליקציה נשארת בחזית. לעדכן את המשתמשים כשיש נתונים חדשים, כדי שיוכלו לעדכן את המסך כך שישקף את השינויים.