建议您遵循以下最佳实践准则,以确保您的应用在与 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 可能会多次启动,例如,如果用户之后撤消了应用的权限,然后重新连接了该应用。