העברת Health Connect מ-Android 13 (APK) ל-Android 14 (מסגרת)

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

מפתחים צריכים להתייחס לקובץ ה-APK של Health Connect (Android 13) כשכבת תאימות לאחור למודל המסגרת. מודל המסגרת ישמור על זהות תכונות מלאה עם קודמו בפורמט APK.

במהלך המעבר מ-Android 13 ל-14, חשוב מאוד שחוויית המשתמש תישאר חלקה ואינטואיטיבית ככל האפשר.

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

תוכנית העברה

  1. אחרי השקת Android 14, Google תתחיל לספק את Health Connect כאפליקציית מערכת של Android.
  2. לאחר מכן, הנתונים ימולאו מ-APK ברגע שתהיה שוויון תכונות.
  3. כל נקודות הכניסה יטרגטו את ממשק המשתמש של אפליקציית המערכת.
  4. העברת הנתונים תתחיל. במהלך ההעברה, ממשקי ה-API של המודול יושהו עם הסטטוס 'ההעברה מתבצעת'. המידע הזה יופיע גם בממשק המשתמש של Health Connect.
  5. אחרי שהמיגרציה תושלם, תוכלו להסיר את קובץ ה-APK.

תרחישים לדוגמה להעברה

הנה כמה תרחישים לדוגמה שמסבירים את תהליך ההעברה של סוגי הנתונים interval ו-series:

דוגמה 1 – ריצה (נתוני מרווחים)

משתמש צבר 10 שנים של רשומות ריצה למשך שעה אחת בכל יום. זה שווה ערך ל:

  • רשומות של סשנים של פעילות גופנית: 365 * 10 * 1
  • שלבים: 365 * 10 * 1
  • קלוריות: 365 * 10 * 1
  • סה"כ = 365 * 10 * 3 (365 * 30) = 10,150

מכיוון שקטע אחד שווה ל-3,000 רשומות, סך הנתונים שלמעלה הוא כ-4 קטעים.

בבדיקות הפנימיות שלנו אושר שהוספה של מקטע רגיל נמשכת בערך שנייה, כך שהנתונים שלמעלה יועברו תוך כ-4 שניות.

דוגמה 2 – דופק (נתוני סדרה)

משתמש אחד אסף נתוני דופק במשך 5 שנים (עם רשומה שנוצרה בכל דקה), בסך 2,628,000 רשומות.

אם יש 3,000 רשומות בכל מקטע, הנתונים מחולקים ל-876 מקטעים. מכיוון שהוספת מקטע אחד נמשכת בערך שנייה, העברת הנתונים תתבצע תוך פחות מ-15 דקות.

תהליך ההעברה המוצע

החלטנו לבחור בהעברה מיידית. בפועל, המשמעות היא ש-APK יהיה לא פעיל ברגע שהמכשיר ישודרג ל-Android 14, עם התערבות מינימלית של המשתמש.

נבחן את תהליך ההעברה ברמה גבוהה:

  1. המשתמש משדרג את המכשיר ל-Android 14.
  2. ב-Jetpack 14 המשתמש מנותב לממשקי ה-API של המודול, והם נחסמים בזמן ההעברה.
  3. תהליך ההעברה מתחיל כשגרסת המודול תואמת ל-APK מבחינת תכונות – כלומר, גרסת המודול מכילה את אותה קבוצת תכונות או יותר. לאחר התחלת תהליך ההעברה, ה-APK מעביר את ההרשאות והנתונים.
    1. אם שתי הגרסאות לא תואמות מבחינת תכונות, תצטרכו לשדרג את גרסת המודול. אחרי שהשדרוג יושלם, תהליך ההעברה יתחיל.
  4. אחרי שהמיגרציה תושלם, המצב ישתנה ל-'Migration Complete' (המעבר הושלם) והחסימות של ממשקי ה-API של המודול יוסרו.
  5. עכשיו אפשר להסיר את קובץ ה-APK.

רכיבים בממשק המשתמש של תהליך ההעברה

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

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

נדרש עדכון בטלפון


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

נדרש עדכון של קובץ ה-APK


איור 3. במהלך תהליך ההעברה יוצג סמל סיבוב עם טקסט שמסביר שהנתונים מסתנכרנים:

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

נתונים ללא כפילויות

אם מודול המסגרת התחיל לאסוף נתונים והרשאות לפני שהתרחשה העברה או שחזור מבוסס-ענן, חלים הכללים הבאים.

הרשאות

אם יש הרשאות במודול של המסגרת, ההרשאות הכפולות שנרכשו מ-APK מתעלמות במהלך תהליך ההעברה.

נתונים

במהלך ההעברה, המערכת מתעלמת מנתונים כפולים שמקורם בקובץ ה-APK. נתונים עדכניים יותר מהמודול מקבלים עדיפות.

הנתונים מנוקים מיותרות ב-clientRecordId אם מזהה הרשומה מסופק על ידי הלקוח. אם לא, מרווחי הזמן (startTime ו-endTime לרשומות פנימיות, ו-time לרשומות מיידיות) נחשבים כמפתח, יחד עם סוג הנתונים ושם החבילה של האפליקציה.

שינויים ב-Jetpack SDK

‏Jetpack SDK משמש כנקודת השילוב המשותפת של קובץ ה-APK של Health Connect וממשקי ה-API של Health Connect Framework.

יצרני ציוד מקורי יכולים להתחיל לשלב עם Jetpack 13, כך שכשהגרסה Jetpack 14 תהיה זמינה, תוכלו להשתמש בספרייה החדשה ולעבד אותה ב-Android 14.

אנחנו נשיק גרסה חדשה של ה-SDK שתתמוך במעבר ל-Android 14. כדי להבטיח מעבר חלק, תצטרכו לבצע כמה שינויים באינטגרציה הקיימת.

הצהרת הרשאות

ב-Android 13, מגדירים הרשאות באמצעות פורמט הרשאות בהתאמה אישית, בקובץ משאב שמקושר למניפסט:

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

כדי לתמוך ב-Android 14, המפתחים צריכים לעבור לפורמט ההרשאות הרגיל:

#AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP” />
<uses-permission android:name=”android.permission.health.READ_WEIGHT” />
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT” />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

פתיחת Health Connect

ברוב האפליקציות של צד שלישי יש לחצן שפותח את אפליקציית Health Connect, כמו הלחצן 'ניהול הגישה' ב-Fitbit.

ב-Android 13, פותחים את אפליקציית Health Connect באמצעות שם החבילה או באמצעות הפעולה androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

ב-Android 14, צריך להשתמש בפעולת כוונה (intent) שצוינה ב-Jetpack SDK, שיש לה ערכים שונים בהתאם לגרסה של Android שבה היא פועלת:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

קבלת לקוח Health Connect

יצרנו ממשק API יחיד בשם sdkStatus, שזמין ב-Jetpack 11, כדי להחליף שני ממשקי API אחרים שהוצאו משימוש – IsSdkSupported() ו-isProviderAvailable().

שינויים ב-API של רשומות סשנים

ארבעת תת-הסוגים של ExerciseSession נמחקו כחלק מהגרסה alpha10:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

בדומה ל-ExerciseSessionRecord, SleepStage יהפוך לסוג משנה של SleepSession.

גם תת-הסוגים של ExerciseSessionRecord וגם השינויים ב-SleepSession יושקו במסגרת עדכון ה-SDK באפריל.

עדכון סוג סשן הפעילות הגופנית

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

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

סוגי ההחלפות:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

טיפול ביומן השינויים

יומני השינויים לא יועברו במסגרת המעבר מ-APK ל-Android 14.

אחרי שהמיגרציה תושלם, תתחילו לקבל חריגות מסוג TOKEN_EXPIRED או TOKEN_INVALID. יש לטפל בהן בדרכים הבאות (בסדר העדיפות הבא):

1. קריאה של כל הנתונים מאז חותמת הזמן 'קריאה אחרונה' או מ-30 הימים האחרונים, וסינון כפילויות

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

2. קריאת נתונים מאז חותמת הזמן 'קריאה אחרונה'

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

3. למחוק את הנתונים מ-30 הימים האחרונים ולקרוא אותם מחדש

למחוק את כל הנתונים שקראו מ-Health Connect ב-30 הימים האחרונים ולקרוא שוב את כל הנתונים האלה (למשל, כמו שמתבצע כשאפליקציות משתלבות עם Health Connect בפעם הראשונה).

4. לא לעשות דבר (כלומר, לקרוא מחדש את הנתונים מ-30 הימים האחרונים ולא לבצע הסרת כפילויות)

מומלץ להשתמש באפשרות הזו רק כצאן אחרון, מאחר שיש סיכון להצגת נתונים כפולים. במקום זאת, המפתחים צריכים לבדוק את האפשרויות 1-3, מאחר שכבר אמורים להיות מוגדר UUID.

בדיקת ממשקי API של Android 14 באמצעות Jetpack SDK

ערכת ה-SDK של Jetpack ל-Android 14 תושק ב-7 ביוני 2023, יחד עם גרסת הבטא 3 של Android 14. כדי להשתמש ב-Android 14 Jetpack SDK, תצטרכו להתחיל להדר את האפליקציה שלכם ל-Android 14.

אם אתם רוצים לבדוק את הפתרון שלכם בגרסאות ה-build של Android Developer Preview לפני 7 ביוני, תוכלו לפנות לנציג התמיכה שלכם ב-Google לקבלת עזרה.

אם רוצים לבדוק את הפתרון בגרסה Beta 3, צריך לבצע את השינויים הבאים ב-APK:

  1. מגדירים את compileSDKPreview = UpsideDownCake.
  2. מעדכנים את המניפסט כך שיכלול כוונה ל-Android 14:
# AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP”/>
<uses-permission android:name=”android.permission.health.READ_WEIGHT”/>
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT”/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
      <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
      </intent-filter>
</activity-alias>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

התאמה אישית של OEM

ב-Android 14, אמצעי הבקרה על הפרטיות וניהול הנתונים ב-Health Connect נמצאים בהגדרות המערכת.

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

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