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

איור של הודעה על כך שנדרש עדכון לטלפון
איור 1: בקשה לעדכן את קובץ ה-APK של Health Connect.

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

נתון שמציין אם נדרש עדכון של ה-APK
איור 2: הנחיה לעדכון מודול המסגרת.

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

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