针对效果进行规划

建议您遵循以下最佳实践准则,以确保您的应用在与 Health Connect 搭配使用时取得良好效果。

写入数据

应用只能将自身来源的数据写入 Health Connect。

如果您应用中的数据是从另一应用导入的,则需由另一应用负责将其自身的数据写入 Health Connect。

此外,最好能实现用于处理写入异常(例如数据超出边界或内部系统出错)的逻辑。您可对作业调度机制应用退避和重试策略。如果最终无法向 Health Connect 写入数据,请确保应用可以越过该导出点。别忘了要记录并报告错误以帮助诊断。

跟踪数据时,您可遵循几条建议,具体取决于应用写入数据的方式。

被动跟踪

以下建议适用于执行被动健身或健康跟踪的应用,例如在后台持续记录步数或心率的应用。

您的应用需要通过以下方式定期将数据写入 Health Connect:

  • 每次同步时,仅写入新数据,并更新自上次同步后发生修改的数据。
  • 对请求进行分块,且每个写入请求的记录数量不超过 1,000 条。
  • 使用 WorkManager 安排周期性后台任务(时限至少为 15 分钟)。
  • 将任务限制为仅在设备空闲且电池电量充足时运行。

    val constraints = Constraints.Builder()
        .requiresBatteryNotLow()
        .requiresDeviceIdle(true)
        .build()
    
    val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
            15,
            TimeUnit.MINUTES,
            5,
            TimeUnit.MINUTES
        )
        .setConstraints(constraints)
        .build()
    

主动跟踪

以下建议适用于执行基于事件的跟踪(例如锻炼和睡眠)或手动用户输入(例如营养摄入)的应用。应用在前台运行或出现应用一天只被使用寥寥几次的罕见事件时,会创建此类记录。

确保应用不会在事件的整个持续期间使 Health Connect 始终保持运行状态。

必须通过以下两种方式之一将数据写入 Health Connect:

  • 在事件完成后将数据同步到 Health Connect。例如,在用户结束一个被跟踪的锻炼时段时同步数据。
  • 使用 WorkManager 安排一次性任务,以便日后需要时同步数据。

采样率

将数据写入 Health Connect 时,请使用适当的采样率,以降低存储空间负载。例如,最好考虑一下多久需要记录一次步数数据,或者与正在进行的锻炼相关的数据类型(比如速度)需要哪种采样率。

并非所有数据类型都需要相同的采样率。例如,每秒更新步数数据几乎没什么好处,不如降低更新频率(例如每 60 秒一次)。不过,如果采样率较高,用户就可以更详尽、更精细地了解自己的健康与健身数据。采样频率需要在细节和性能之间取得平衡。

同步数据

以下因素会影响同步过程。

令牌过期

由于闲置的更改令牌会在 30 天内过期,因此您必须遵守同步策略,以避免在此类情况下丢失信息。您的策略可以采用以下方法:

  • 在应用的数据存储区中搜索最近用过的记录,记录中还应具有来自 Health Connect 的 id
  • 向 Health Connect 请求以特定时间戳开头的记录,然后在应用的数据存储区中插入或更新这些记录。
  • 请求一个更改令牌以备下次需要时使用。

建议的更改管理策略

如果应用获取的更改令牌无效或已过期,我们建议您根据该令牌在应用逻辑中的使用方式,采取以下管理策略:

  • 读取所有数据并对其进行去重处理。这是最理想的策略。
    • 存储上次从 Health Connect 读取数据的时间戳。
    • 在令牌过期后,重新读取自最近时间戳以来或过去 30 天内的所有数据。然后,使用标识符对照之前读取的数据对其进行去重处理。
    • 最好实现客户端 ID,因为在更新数据时需要用到该 ID。
  • 只读取自上次读取时间戳以来的数据。这会导致在更改令牌过期前后出现一些数据差异,不过这段时间较短,可能是几个小时到几天。
    • 存储上次从 Health Connect 读取数据的时间戳。
    • 在令牌过期后,读取从这个时间戳开始的所有数据。
  • 删除过去 30 天内的数据,然后再读取该数据。此操作更适合在首次集成时执行。
    • 删除该应用在过去 30 天内从 Health Connect 读取的所有数据。
    • 删除后,重新读取所有这些数据。
  • 读取过去 30 天内的数据,但不进行去重处理。这是下下之策,会导致向用户显示重复数据。
    • 删除该应用在过去 30 天内从 Health Connect 读取的所有数据。
    • 允许条目重复。

数据类型更改令牌

如果您的应用可以独立使用多种类型的数据,则针对每种数据类型使用单独的更改令牌。仅当这些类型的数据被一起使用或不被使用时,才借助 Changes Sync API 来利用多种数据类型。

前台读取

应用只有在前台运行时才能读取来自 Health Connect 的数据。同步 Health Connect 中的数据时,对 Health Connect 的访问可能会随时中断。例如,从 Health Connect 读取大量数据时,您的应用必须在同步过程中处理中断,并在下次打开应用时继续。

数据导入时间

由于应用无法在有新数据时收到通知,因此需在以下两个时间点检查是否有新数据:

  • 每当应用在前台进入活动状态时。在这种情况下,请使用生命周期事件。
  • 应用持续在前台运行时。在这种情况下,应定期检查。在有新数据可用时通知用户,让对方更新界面以反映更改。

速率限制

在极少数情况下,Health Connect 会对来自应用的请求施加速率限制。此举旨在限制对电池的影响以及设备性能。

  • 我们强烈建议您遵循最佳实践准则,以防止您的应用请求由于速率限制而被拒。
  • 应用应能够灵活应对速率限制。例如,如果请求因速率限制而失败,则可以在下一个周期性任务期间写入后台数据。

为应用配置新用户引导流程

许多应用都有自定义的新用户引导流程,例如功能教程或征求用户同意。我们强烈建议开发者,将用户首次与 Health Connect 应用互动时该应用会启动的新用户引导 activity 导出来。为此,请在清单中添加以下代码:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

请注意,Android 14 中尚未推出对此功能的支持,但很快就会推出。

当用户尝试将您的应用连接到 Health Connect 时,系统会启动导出的 activity。此 activity 必须执行以下操作:

  • 显示任何相关的用户教程,例如说明系统会写入或读取哪些数据。
  • 视需要征求用户同意。
  • 向 Health Connect 发出权限请求。
  • 执行任何其他特定于应用的逻辑,例如调度一项定期 worker。
  • 完成后,允许用户关闭此 activity。

对于不导出新用户引导 activity 的应用,当用户尝试连接应用时,Health Connect 会改为将用户带到管理权限界面。对于需要授予权限是确保集成正常运行的唯一前提条件的应用,这种做法可能是可以接受的。

请注意,新用户引导 activity 可能会多次启动,例如,如果用户之后撤消了应用的权限,然后重新连接了该应用。