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

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

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

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

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

תוכנית העברה

1. אחרי ש-Android 14 תושק, Google תתחיל לספק את Health Connect כאפליקציית מערכת ל-Android.
2. לאחר מכן, יתבצע מילוי חוסרים (backfill) של הנתונים מ-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,950

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

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

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

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

הרשאות

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

נתונים

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

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

שינויים ב-Jetpack SDK

ערכת Jetpack SDK משמשת כנקודת שילוב משותפת גם ל-APK של Health Connect וגם לממשקי ה-API של מסגרת Health Connect.

יצרני ציוד מקורי (OEM) יכולים להתחיל לשלב את 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().

שינויים ב-Session record API

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

• 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

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

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

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

1. מגדירים את compileSDKPreview = UpsideDownCake.
2. מעדכנים את המניפסט כך שיכלול Intent ל-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) באמצעות שימוש בשכבות-על בהתאמה אישית.

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