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

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

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