将 Health Connect 从 Android 13 (APK) 迁移到 Android 14 (框架)

Health Connect 将作为 Android 14 的一个通用数据存储层打包，用于存储消费者健康数据，受细粒度权限保护，并可作为 Android 系统应用访问（本文档中称为“框架”模块）。

开发者应将 Health Connect APK（Android 13）视为框架模型的向后兼容层。框架模型将保持与其 APK 前身的 100% 功能一致性。

在从 Android 13 迁移到 14 的过程中，至关重要的是，用户体验保持尽可能流畅和直观。

本文档概述了迁移计划，提供了一些示例迁移场景，并列出了 Jetpack SDK 的更改，这些更改有助于访问 Health Connect API。

迁移计划

Android 14 发布后，Google 将切换到将 Health Connect 作为 Android 系统应用提供。
一旦实现功能一致性，数据将从 APK 后续填充。
所有入口点都将指向系统应用 UI。
数据迁移将开始。在迁移进行期间，模块 API 将暂停，状态为“迁移进行中”。这也会在 Health Connect UI 中显示。
迁移完成后，可以卸载 APK。

示例迁移场景

以下是一些示例场景，解释了 interval 和 series 数据类型的迁移过程

示例 1 - 跑步（区间数据）

用户收集了 10 年的跑步记录，每天 1 小时。这相当于

运动会话记录：365 * 10 * 1
步数：365 * 10 * 1
卡路里：365 * 10 * 1
总计 = 365 * 10 * 3 (365 * 30) = 10,150

鉴于 1 个块相当于 3,000 条记录，上述数据总计约为 4 个块。

内部测试已确认，插入一个典型数据块大约需要一秒钟，因此上述数据迁移大约需要4秒钟。

示例2 - 心率（序列数据）

一位用户收集了5年的心率数据（每分钟创建一个记录），总共有2,628,000条记录。

每块数据包含3,000条记录，这些数据分布在876个数据块中。假设插入一个数据块大约需要一秒钟，则数据迁移将在15分钟内完成。

建议的迁移流程

我们决定采用**即时迁移**。实际上，这意味着一旦设备升级到Android 14，APK将立即失效，用户干预最少。

让我们来看一下高级别的迁移流程

用户将设备升级到Android 14。
Jetpack 14将用户引导至模块API，并在迁移过程中阻止用户访问。
当模块版本与APK的功能兼容时，迁移过程开始——即模块版本包含相同或更多功能。迁移过程启动后，APK将迁移权限和数据。
1. 如果两个版本的功能不兼容，则需要升级模块版本。升级完成后，迁移过程将开始。
迁移完成后，状态将更改为“迁移完成”，模块API将被解除阻塞。
现在可以卸载APK。

迁移UI元素

框架模块显示以下屏幕，用于用户教育目的，包括迁移之前和迁移期间

图1.如果Health Connect APK“未感知迁移”，则会显示提示，指示用户更新APK。如果用户拒绝更新，模块将继续运行并开始积累权限和数据。

Phone update required

图2.如果框架模块需要更新才能实现功能兼容，则会显示提示，要求用户执行更新并重新启动设备。如果用户拒绝更新，模块将继续运行并开始积累权限和数据。

APK update needed

图3.迁移过程中会显示一个旋转指示器，并显示正在同步数据的文本。

Data Syncing

数据去重

如果框架模块在任何迁移或基于云的恢复发生之前就开始获取数据和权限，则适用以下规则。

权限

如果框架模块中存在权限，则在迁移过程中将忽略从APK获取的任何重复权限。

数据

在迁移过程中，将忽略源自APK的重复数据。优先考虑来自模块的较新数据。

如果客户端提供记录ID，则根据clientRecordId对数据进行去重。如果没有提供，则时间间隔（内部记录的startTime和endTime，以及即时记录的time）将被视为键，以及应用程序的数据类型和包名。

Jetpack SDK中的更改

Jetpack SDK作为Health Connect APK和Health Connect框架API的通用集成点。

OEM厂商可以开始与Jetpack 13集成，以便在Jetpack 14可用时，能够采用新的库并在Android 14中进行编译。

我们将发布支持Android 14过渡的新版SDK。您需要对现有集成进行一些更改，以确保顺利过渡。

权限声明

在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中，您可以使用包名或通过androidx.health.ACTION_HEALTH_CONNECT_SETTINGS操作来打开Health Connect应用程序。

在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天的所有数据进行去重。

存储应用程序上次从Health Connect读取数据的的时间戳。令牌过期时，应从此值或前30天（取较小值）重新读取数据，并使用UUID对其与先前读取的数据进行去重。

2. 读取“上次读取”时间戳以来的数据。

建立一个时间戳，指示上次从Health Connect读取数据的时间，并在令牌过期时，读取该值之后的全部数据。

3. 删除并重新读取过去30天的数据。

删除过去30天从Health Connect读取的所有数据，并再次读取所有这些数据（例如，应用程序首次与Health Connect集成时所执行的操作）。

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 POC寻求帮助。

如果您想针对Beta 3版本进行测试，您应该在APK中进行以下更改：

设置compileSDKPreview = UpsideDownCake。
更新清单以包含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移动服务文档。