将 Health Connect 从 Android 13（APK）迁移到 Android 14（框架）

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

开发者应将 Health Connect APK (Android 13) 视为框架模型的向后兼容层。框架模型将与其 APK 前身保持 100% 的功能对等。

在从 Android 13 到 14 的过渡期间，用户体验保持尽可能流畅和直观至关重要。

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

迁移计划

  1. Android 14 发布后，Google 将切换为提供作为 Android 系统应用的 Health Connect。
  2. 一旦实现功能对等，数据将从 APK 回填。
  3. 所有入口点都将指向系统应用界面。
  4. 数据迁移将开始。在迁移过程中，模块 API 将暂停，并显示“迁移进行中”状态。这在 Health Connect 界面中也将可见。
  5. 迁移完成后，即可卸载 APK。

示例迁移场景

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

示例 1 - 跑步（interval 数据）

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

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

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

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

示例 2 - 心率（series 数据）

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

按每个数据块 3,000 条记录计算，数据分布在 876 个数据块中。鉴于 1 个数据块插入大约需要一秒钟，数据将在 15 分钟内迁移完成。

建议的迁移流程

我们决定采用即时迁移。实际上，这意味着设备一升级到 Android 14，APK 就会变为非活跃状态，且用户干预最少。

让我们来看一下高层次的迁移流程

  1. 用户将其设备升级到 Android 14。
  2. Jetpack 14 将用户路由到模块 API，并在迁移进行时阻止它们。
  3. 当模块版本与 APK 功能兼容时（即模块版本包含相同或更多的功能集），迁移过程就会开始。一旦迁移过程开始，APK 就会迁移权限和数据。
    1. 如果两个版本功能不兼容，则需要升级模块版本。升级完成后，迁移过程将开始。
  4. 迁移完成后，状态将更改为“迁移完成”，并且模块 API 将解除阻止。
  5. 现在可以卸载 APK。

迁移界面元素

以下屏幕由框架模块在迁移之前和迁移期间显示，用于用户教育

图 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 的通用集成点。

原始设备制造商可以开始集成 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 中，您可以使用包名打开 Health Connect 应用，也可以通过 androidx.health.ACTION_HEALTH_CONNECT_SETTINGS 操作打开。

在 Android 14 中，您需要使用 Jetpack SDK 中指定的 intent 操作，该操作根据其作用的 Android 版本具有不同的值

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

获取 Health Connect 客户端

我们创建了一个单一 API，名为 sdkStatus，可在 Jetpack 11 中使用，以取代另外两个已弃用的 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 中进行以下更改：

  1. 将 compileSDKPreview 设置为 UpsideDownCake。
  2. 更新清单以包含适用于 Android 14 的 intent
# 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>

原始设备制造商定制

在 Android 14 中，Health Connect 的隐私和数据管理控件位于“系统设置”中。

为了使数据管理和权限屏幕看起来和感觉上像是设备的一部分，Health Connect 通过使用自定义覆盖层提供原始设备制造商主题化。

有关原始设备制造商样式文档，请查阅 Health Connect Google 移动服务文档。您可能需要登录 Google 开发者账号才能查看该页面。