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

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


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

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

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

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

הרשאות

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

נתונים

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

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

שינויים ב-Jetpack SDK

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

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