提升应用在所有 Wear OS 设备上的兼容性

Wear Health Services API (WHS) 是所有搭载 Wear OS 3 及更高版本的设备的必备组件，因为它可为健康与健身应用开发者提供一致的集成接口。您可以构建应用使其很好地适应多种设备及其不同功能，从而保持应用在各种设备上的兼容性并避免用户体验问题。要想这样做，请只对应用使用的客户端声明依赖项。此外，还要让应用能够根据可用性灵活地显示或移除可选高级指标。

不同的传感器按照不同的频率生成数据，具体情况因设备而异，取决于底层硬件和传感器平台。例如，某个设备可能会在一个时间戳处返回心率，在另一个时间戳处返回位置信息。因此，请创建能够在不同或重叠的时间戳处接收独立数据流的应用。

本指南将介绍 Wear 健康服务中各客户端的预期行为及其支持的数据类型。

运动客户端

以下部分将介绍 ExerciseClient 的预期行为和数据类型。

预期行为

对于 ExerciseClient，有一些运动类型依赖于特定数据类型的可用性。例如，只有在支持推轮椅运动的情况下才能使用轮椅运动。请根据这些选项在给定设备上的可用性启用和停用这些选项。

大多数运动数据类型都按一秒的间隔时间进行采样和传输，但也有一些例外情况：

  • 在某些情况下，有些运动数据类型会每秒更新多次。例如，当用户跑步时，步数就会每秒更新多次。
  • 对于某些数据类型，只有在当前值与先前值不同的情况下，系统才会传输更新。

数据传输可采用流式传输或批量处理。应用处理器开启时（通常是在显示屏开启且可互动时），对数据进行流式传输。当显示屏关闭或进入氛围模式（开启但处于非互动状态）后，系统会批量处理数据以节省电量。当应用处理器重新开启（因为手表退出氛围模式或批量处理缓冲区已满，具体情况因设备而异）时，系统会将批量处理的数据传输给应用。采样率在设备处于氛围模式时保持不变，因此传输的批量数据仍具有高频数据点。

数据类型仅由手表上的传感器所生成的数据派生而来。例如，位置数据完全来自手表，而不会来自手机。

数据类型

借助 ExerciseClient API，您可以开始、暂停、恢复和停止不同类型的锻炼。对于每一项运动，WHS 都针对该运动类型定义了一组数据类型供您使用。这可以节省电量并简化应用逻辑，因为给定运动所不需要的传感器就不会开启。例如，开始跑步时，系统只会在户外跑步时提供和跟踪位置数据。开始骑自行车运动时，系统不会提供或跟踪步数。以下部分将介绍 ExerciseClient 中支持的数据类型。

保证支持的运动数据类型

以下运动数据类型在所有设备上都可以使用。

  • 采样数据类型具有相应的 _STATS 数据类型，返回运动中的最小值、最大值和平均值。例如，可以使用 PACE_STATS 数据类型提取 PACE 统计数据。
  • 间隔数据类型具有相应的 _TOTAL 数据类型，返回运动中的累计值。例如，可以使用 DISTANCE_TOTAL 数据类型提取 DISTANCE 统计数据。
指标 预期数据 关于预期行为的说明
HEART_RATE_BPM 每分钟心跳次数 [数据类型：Double] 所有设备都会在运动过程中每秒采集一次心率。有些设备每秒报告一次 BPM 值。有些设备仅在上次报告 BPM 值之后该值发生变化时才会报告 BPM。不要指望每台设备上都会每间隔一秒收到一次 BPM 值。
LOCATION 纬度和经度 [数据类型：Double] 位置数据仅仅基于手表的 GPS 数据。也就是说，位置数据不会来自一体化位置信息提供程序或其他 Android 服务。每个数据点还包含精度值（也称为水平位置错误）和可用性信息。
STEPS [数据类型：Long] 步数是运动期间（不含运动暂停的时间）跑的总步数
DISTANCE 米 [数据类型：Double] 如果有基于 GPS 的位置信息，则根据此位置信息计算，否则通过步数计算。总数是指运动期间（不含运动暂停的时间）跑的总长。
SPEED [米/秒] [数据类型：Double] 返回最小值、最大值和平均值。这些都是运动期间（不含运动暂停的时间）的数据。
PACE [秒/米] [数据类型：Double] 如果速度为 0，默认值就为 0。平均值是运动期间（不含运动暂停的时间）的数据。
ELEVATION_GAIN 米。[数据类型：Double] 海拔的正变动。系统会在运动期间（不含运动暂停的时间）报告总数。
TOTAL_CALORIES 千卡 [数据类型：Double] 运动消耗的卡路里数将增加到基础代谢率中。此处发出的卡路里数会考虑系统设置中指定的用户身高、体重、年龄和性别。但是，这些卡路里数不会考虑您的应用中收集的任何用户个人资料数据。所报告的总数是运动期间（不含运动暂停的时间）的数据。

可选的运动数据类型

下面列出的数据类型仅适用于特定设备。如需查看数据类型的完整列表，请参阅 Jetpack 参考文档。如果某个数据类型不在前文列出的“必备/保证支持”数据类型中，就属于可选数据类型。

请参阅以下可选数据类型示例。下表并未列出所有可选数据类型：

指标 预期数据 关于预期行为的说明
ABSOLUTE_ELEVATION [数据类型：Double]
ELEVATION_LOSS 米 [数据类型：Double] 海拔的负变动。该值为正数。例如，海拔下降 1 米，返回的是 1 而不是 -1。
STEPS_PER_MINUTE [数据类型：Long]
WHEELCHAIR_PUSHES [数据类型：Long] 推轮椅的次数，适用于使用轮椅进行的运动。
REP_COUNT [数据类型：Long]
SWIM_STROKE_COUNT [数据类型：Long]
SWIM_LAP_COUNT [数据类型：Long]

每种运动的数据类型

系统会针对每种运动类型返回不同的数据类型。返回的数据类型与运动的需求一致。例如，BIKING 运动类型不会返回 STEPS 数据类型。请在运行时使用 Capabilities 方法来确定用户设备上支持的数据类型。

至少，所有运动类型都会返回心率和卡路里数据。其他运动可能还支持其他数据类型，具体取决于对运动的要求。

示例如下：

  • 冥想或普拉提等运动仅支持心率和卡路里
  • 篮球或羽毛球等运动支持心率、卡路里、距离和步数
  • 步行和跑步等运动支持心率、卡路里、距离、步数、速度和步速
  • 游泳支持心率、卡路里、距离和游泳圈数

被动监控客户端

所有搭载 Wear OS 的设备若要支持被动监控健康数据（例如心率和步数）的应用，必须支持以下数据类型。下述每种数据类型都必须仅由手表上的传感器所生成的数据派生而来。

预期行为

为节省电量，使用被动监控获得的传感器读数存储在 MCU 上，并批量传输给健康服务。这些批处理结果按照不同的间隔时间返回，具体取决于系统行为。例如，当传感器缓冲区已满或用户与显示屏互动时，就会返回批量结果。

不要针对任何数据类型假定任何预定义或可预测的批处理间隔时间。

被动监控数据类型

指标 预期数据 备注
HEART_RATE_BPM 每分钟心跳次数 [数据类型：Double] 设备可能会按照不同的间隔时间返回心率读数。有些设备可能每秒获取一次读数。其他设备可能每十分钟获读一次读数。这些间隔时间并不供应用使用。不过，应用应该能够很好地适应不同的采样间隔时间。
STEPS_DAILY/STEPS [数据类型：Long] 每日步数是指自上次重置（由 WHS 在午夜触发）以来获取的总步数。此数据包括进行中的运动暂停期间获取的所有步数。步数是自上次检查以来所增加步数的精细数据。
DAILY/DISTANCE 米 [数据类型：Double] 通过加速度计/步数计算得出。为了确保关闭位置信息服务的用户仍可获得准确的步数，请勿在使用 GPS 期间进行计算。
SPEED [米/秒] [数据类型：Double]
CALORIES_DAILY 千卡 [数据类型：Double] 一天的卡路里数，包括运动消耗的卡路里数和 BMR。此处发出的卡路里数据会考虑系统设置中指定的用户身高、体重、年龄和性别。但是，这些卡路里数不会根据您的应用中收集的任何用户个人资料数据进行调整。
RUNNING_STEPS（可选） [数据类型：Long] 运动期间和其他情况下增加的步数。同时跟踪这两种数据。
WALKING_STEPS（可选） [数据类型：Long]
ELEVATION_GAIN 米 [数据类型：Double] 只包含海拔的正增加
ELEVATION_LOSS 米 [数据类型：Double] 只包含海拔的负增加
FLOORS_DAILY [数据类型：Double] 可以表示为“部分”楼层

被动监控每日目标

指标 预期数据 备注
每日步数 [数据类型：Long] 每日步数（包括进行中的运动暂停期间获取的所有步数）是指自上次重置以来获取的总步数。WHS 在午夜重置。
FLOORS_DAILY [数据类型：Double] 可以表示为“部分”楼层。
CALORIES_DAILY 千卡 [数据类型：Double] 一天的卡路里数，包括运动消耗的卡路里数和 BMR。
每天 DISTANCE_DAILY 米 [数据类型：Double] 通过加速度计或步数计算得出。请勿使用 GPS 计算此数据，以便关闭位置信息服务的用户仍可获得准确的步数。
DAILY_ELEVATION_GAIN 米 [数据类型：Double] 只包含海拔的正增加

MeasureClient

MeasureClient 用于测量给定时间的心率。

预期行为

MeasureClient 和 PassiveClient 在某些方面比较相似。二者都可提供非批量处理且与运动无关的健康统计数据。您可以同时使用这两者来衡量心率，但主要区别在于 MeasureClient 包含心率数据可用性，而 PassiveClient 不包含可用性信息。

数据类型

指标 预期数据 备注
HEART_RATE_BPM 每分钟心跳次数 [数据类型：Double] 也包含可用性信息

支持的功能

除了运动数据类型和被动监控数据类型外，设备还支持用于触发事件的其他功能，例如开始运动和测量状态（例如，睡眠与清醒）。其中一些功能是所有设备上都存在的功能，而其他功能则只在部分设备上提供。

事件触发器

所有设备都支持以下常用触发器：

  • 每日距离和步数目标
  • 运动步数、距离和时长目标。

其他设备可能还支持更高级的事件触发器。以下是一些示例：

  • 游泳时计算圈数
  • 运动消耗卡路里数目标
  • 运动瞬时速度目标

状态

所有设备都支持基本状态功能。状态功能是指用户当前是否正在进行运动

其他设备可能还提供其他状态功能。其他状态功能包括检测运动是否已自动暂停或自动恢复，或者用户何时处于清醒状态或睡眠状态。

被动监控中的健康提醒

某些设备支持健康提醒。并非所有设备都支持这些功能。健康提醒包括检测心率异常或检测跌倒情况。