將 Health Connect 從 Android 13 (APK) 遷移至 Android 14 (架構)

「健康資料同步」將與 Android 14 一同封裝，做為消費者健康與健身資料的通用資料儲存層，受到精細權限保護，並且能以 Android 系統應用程式的形式存取 (在本文件中統稱為「架構」模組)。

開發人員應將健康資料同步 APK (Android 13) 視為架構模型的回溯相容層。這個架構模型將保留與 APK 之前的版本完全對等的功能。

從 Android 13 轉換至 14 時，請盡可能提供流暢且符合直覺的使用者體驗。

本文件將概略說明遷移計畫、提供一些遷移情境示例，並列出方便您存取 Health Connect API 的 Jetpack SDK 相關異動。

遷移計畫

  1. Android 14 發布後，Google 會改以 Android 系統應用程式形式提供「健康資料同步」。
  2. 一旦功能一致，系統就會從 APK 中補充資料。
  3. 所有進入點都會以系統應用程式 UI 為指定目標。
  4. 資料遷移作業即將開始。在遷移作業進行時，模組 API 會遭到暫停，並顯示「遷移中」狀態。此狀態也會在「健康資料同步」使用者介面中顯示。
  5. 遷移作業完成後，即可解除安裝 APK。

遷移情境示例

以下情境示例說明 interval 和 series 資料類型的遷移程序：

示例 1：跑步 (間隔資料)

使用者收集了 10 年份的跑步記錄，每天跑步一小時。這項資料相當於：

  • 運動時數記錄：365 * 10 * 1
  • 步數：365 * 10 * 1
  • 卡路里：365 * 10 * 1
  • 總計 = 365 * 10 * 3 (365 * 30) = 10,950

由於 1 個區塊相當於 3,000 筆記錄，因此資料共約有 4 個區塊。

經過我們的內部測試確認，插入典型區塊約需一秒鐘時間，因此範例中的資料大約會在 4 秒內遷移完畢。

示例 2：心率 (系列資料)

使用者已收集 5 年份的心率資料 (每分鐘建立記錄)，總共有 2,628,000 筆記錄。

每個區塊有 3,000 筆記錄，資料分布在 876 個區塊中。插入 1 個區塊約需一秒鐘時間，因此上述資料大約會在 15 分鐘內遷移完畢。

建議遷移流程

我們決定選擇立即遷移。實際上，這表示當裝置升級至 Android 14 後，APK 會隨即停用，盡可能減少使用者介入。

以下是遷移流程的概略說明：

  1. 使用者將裝置升級至 Android 14。
  2. Jetpack 14 會將使用者轉送至模組 API，並在遷移作業進行期間封鎖這些 API。
  3. 當模組版本與 APK 的功能相容 (例如模組版本包含相同或更多功能集) 時，就會開始進行遷移程序。遷移程序開始後，APK 會遷移權限和資料。
    1. 如果兩個版本的功能不相容，則需要升級模組版本。升級完成後，系統會開始遷移程序。
  4. 遷移作業完成後，狀態會變更為「遷移完成」，系統也會將模組 API 解除封鎖。
  5. 現在可以解除安裝 APK。

遷移 UI 元素

在遷移期間前後，系統會顯示以下畫面，用來引導使用者：

圖 1. 如果「健康資料同步」APK 未處於「遷移感知」狀態，系統會顯示提示，引導使用者更新 APK。如果使用者拒絕更新，模組會繼續運作，並開始累積權限和資料。

必須更新手機的圖示
圖 1：更新 Health Connect APK 的提示。

圖 2. 如果架構模組需要更新才能使功能相容，系統會顯示提示，要求使用者執行更新並重新啟動裝置。如果使用者拒絕更新，模組會繼續運作，並開始累積權限和資料。

必須更新 APK 的圖示
圖 2：更新架構模組的提示。

圖 3. 遷移程序中會顯示旋轉圖示，並以文字說明當下正在同步處理資料。

資料同步圖
圖 3：資料遷移作業進行中。

刪除重複的資料

如果架構模組在開始進行遷移或雲端還原「之前」，已經開始取得資料和權限，則適用下列規則。

權限

假使架構模組中有權限，在遷移過程中，系統會忽略從 APK 取得的所有重複權限。

資料

在遷移期間，系統會忽略來自 APK 的重複資料，並優先採用來自模組的最新資料。

如果記錄 ID 是由用戶端提供，系統會刪除 clientRecordId 上的重複資料。否則，系統會將時間間隔 (startTime 和 endTime 用於內部記錄，time 用於即時記錄)、資料類型和應用程式套件名稱視為鍵。

Jetpack SDK 的異動

Jetpack SDK 可做為 Health Connect APK 和 Health Connect 架構 API 的通用整合點。

原始設備製造商 (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

大多數第三方應用程式都提供可開啟「健康資料同步」應用程式的按鈕，例如 Fitbit 的「管理存取權」按鈕。

在 Android 13 中，您可以使用套件名稱或透過 androidx.health.ACTION_HEALTH_CONNECT_SETTINGS 動作開啟「健康資料同步」應用程式。

在 Android 14 中，您需要使用 Jetpack SDK 中指定的意圖動作，這個動作會根據正在執行操作的 Android 版本而有不同的值：

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

取得 Health Connect 用戶端

我們在 Jetpack 11 建立了 sdkStatus 這個 API，取代其他兩個已淘汰的 API：IsSdkSupported() 和 isProviderAvailable()。

時段記錄 API 變更

alpha10 版本中刪除了四個 ExerciseSession 子類型，如下所示：

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

和 ExerciseSessionRecord 一樣，SleepStage 會成為 SleepSession 的子類型。

ExerciseSessionRecord 子類型和 SleepSession 變更都會在 4 月的 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 天內以來的所有資料

儲存應用程式上次從「健康資料同步」讀取資料時的時間戳記。權杖過期時，您應從這個值重新讀取資料，或讀取過去 30 天內的資料 (兩者均等同於最短時間)，然後使用 UUID 刪除先前讀取的重複資料。

2. 讀取自「上次讀取」時間戳記以來的資料

建立時間戳記，指出上次從「健康資料同步」讀取資料的時間，並在權杖過期後，讀取該值「之後」的所有資料。

3. 刪除及重新讀取過去 30 天的資料

刪除過去 30 天內從「健康資料同步」讀取的所有資料，然後再次讀取這些資料 (例如在應用程式首次與「健康資料同步」整合時進行這項操作)。

4. 不執行任何動作 (例如，重新讀取過去 30 天的資料，且不刪除重複資料)

請將此方法做為最終手段，因為這有顯示重複資料的風險。由於 UUID 應該已就緒，開發人員應改為探索選項 1 到 3。

使用 Jetpack SDK 測試 Android 14 API

Android 14 Jetpack SDK 預計將在 2023 年 6 月 7 日與 Android 14 的 Beta 3 版一同發布。您必須開始針對 Android 14 編譯應用程式，才能使用 Android 14 Jetpack SDK。

如果您想在 6 月 7 日以前對 Android 開發人員預覽版測試解決方案，請諮詢 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 隱私權和資料管理控制項位於「系統設定」中。

為了讓資料管理和權限畫面的外觀與風格更像是裝置本身的一部分，健康資料同步可使用自訂疊加畫面提供原始設備製造商 (OEM) 主題設定。

如需 OEM 樣式說明文件，請參閱 Health Connect Google 行動服務說明文件。您可能需要登入 Google 開發人員才能查看該頁面。