Wear 健康服务 API (WHS) 是所有运行 Wear OS 3 及更高版本的设备的强制组件,因为它为健康和健身开发者提供了一致的集成界面。构建您的应用,使其能够优雅地适应多种设备及其不同的功能,以保持设备兼容性并避免用户体验问题。为此,仅声明您的应用使用的客户端的依赖项。此外,根据可选高级指标的可用性,允许您的应用灵活地显示或删除这些指标。
不同的传感器以不同的频率生成数据,这些频率根据底层硬件和传感器平台而异。例如,设备可能会在一个时间戳返回心率,在另一个时间戳返回位置。创建能够以不同时间戳或重叠时间戳接收独立数据流的应用。
本指南介绍了 Wear 健康服务中各种客户端的预期行为和支持的数据类型。
锻炼客户端
以下部分描述了 ExerciseClient
的预期行为和数据类型。
预期行为
对于 ExerciseClient
,某些锻炼类型取决于某些数据类型的可用性。例如,轮椅锻炼仅在支持轮椅推动时可用。根据这些选项在给定设备上的可用性来启用和禁用它们。
大多数锻炼数据类型以一秒间隔进行采样和交付,但也有例外。
- 在某些情况下,某些锻炼数据类型每秒更新不止一次。例如,当用户跑步时,步数每秒更新不止一次。
- 对于某些数据类型,仅当当前值与先前值不同时才传递更新。
数据传递可以是流式传输或批量传输。当应用程序处理器开启时,数据以流式传输,这通常发生在显示屏开启并可交互时。一旦显示屏关闭或进入环境模式(开启但不可交互),数据就会批量传输以节省电量。批量数据在应用程序处理器再次开启时(由于手表退出环境模式)或批量缓冲区已满时(因设备而异)交付给应用程序。在设备处于环境模式时,采样率保持不变,因此交付的批次仍具有高频数据点。
数据类型仅来源于手表传感器生成的数据。例如,位置数据完全来自手表,而不是手机。
数据类型
ExerciseClient
API 允许您开始、暂停、恢复和停止不同类型的锻炼。对于每种锻炼,WHS 定义了一组可供该锻炼类型使用的数据类型。这可以节省电量并简化您的应用逻辑,因为不需要的传感器不会在给定锻炼中开启。例如,开始跑步时,位置数据仅用于室外跑步并进行跟踪。开始骑行锻炼时,不提供或跟踪步数。以下部分描述了 ExerciseClient
中支持的数据类型。
保证的锻炼数据类型
所有设备上都提供以下锻炼数据类型。
- 示例数据类型具有相应的 _STATS 数据类型,它返回锻炼的最小值、最大值和平均值。例如,PACE 统计数据可以通过 PACE_STATS 数据类型提取。
- 间隔数据类型具有相应的 _TOTAL 数据类型,它返回锻炼的累积值。例如,DISTANCE 统计数据可以通过 DISTANCE_TOTAL 数据类型提取。
指标 | 预期数据 | 预期行为注意事项 |
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] | 活动卡路里消耗量加上基础代谢率。此处发出的卡路里考虑了系统设置中指定的用户身高、体重、年龄和性别。卡路里不考虑您应用中收集的任何用户资料数据。报告的总数在锻炼期间,不包括锻炼暂停的时间。 |
可选锻炼数据类型
以下数据类型列表仅在某些设备上可用。有关 DataTypes 的完整列表,请参阅 Jetpack 参考。如果 DataType 不在前面的“必需/保证”列表中,则它是可选的。
请参阅以下可选数据类型的示例。此列表并非详尽无遗。
指标 | 预期数据 | 预期行为注意事项 |
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 在午夜触发)以来的总步数。这包括在主动锻炼暂停期间采取的任何步数。“步数”是自上次检查以来的精细增量。 |
DISTANCE_DAILY/DISTANCE(每日距离/距离) | 米 [数据类型:Double] | 从加速度计/步数计算。不要在 GPS 期间计算,以确保已关闭位置服务的用户仍能收到准确的步数。 |
SPEED(速度) | [米/秒] [数据类型:Double] | |
CALORIES_DAILY(每日卡路里) | 千卡 [数据类型:Double] | 当天的卡路里,包括活动卡路里和基础代谢率。此处发出的卡路里值考虑了系统设置中指定的用户身高、体重、年龄和性别。卡路里不根据您应用中收集的任何用户资料数据进行调整。 |
RUNNING_STEPS(跑步步数)(可选) | [数据类型:Long] | 锻炼期间和其他时间的步数增量。同时跟踪两者。 |
WALKING_STEPS(步行步数)(可选) | [数据类型:Long] | |
ELEVATION_GAIN(海拔增益) | 米 [数据类型:Double] | 仅包含海拔的正向增量 |
ELEVATION_LOSS(海拔损失) | 米 [数据类型:Double] | 仅包含海拔的负向增量 |
FLOORS_DAILY(每日楼层) | [数据类型:Double] | 可以表示为“部分”楼层 |
被动监测每日目标
指标 | 预期数据 | 注意事项 |
STEPS_DAILY(每日步数) | [数据类型:Long] | 每日步数,包括在主动锻炼暂停期间采取的任何步数,是自上次重置以来的总步数。WHS 在午夜重置。 |
FLOORS_DAILY(每日楼层) | [数据类型:Double] | 可以表示为“部分”楼梯楼层。 |
CALORIES_DAILY(每日卡路里) | 千卡 [数据类型:Double] | 当天的卡路里,包括活动卡路里和基础代谢率。 |
DISTANCE_DAILY(每日距离) | 米 [数据类型:Double] | 通过加速度计或步数计算。不要使用 GPS 计算此项,以便已关闭位置服务的用户仍能收到准确的步数。 |
DAILY_ELEVATION_GAIN(每日海拔增益) | 米 [数据类型:Double] | 仅包含海拔的正向增量 |
测量客户端
使用 MeasureClient
测量给定时刻的心率。
预期行为
MeasureClient
和 PassiveClient
在某些方面相似。它们都提供与锻炼无关的非批量健康统计数据。您可以使用它们来测量心率,但主要区别在于 MeasureClient
包含心率数据可用性,而 PassiveClient
不包含可用性信息。
数据类型
指标 | 预期数据 | 注意事项 |
HEART_RATE_BPM(心率每分钟) | 每分钟心跳次数 [数据类型:Double] | 也包括可用性 |
支持的功能
除了锻炼数据类型和被动监测数据类型之外,设备还支持用于触发事件(例如开始锻炼)和测量状态(例如清醒与睡眠)的其他功能。其中一些功能存在于所有设备上,而另一些则仅存在于某些设备上。
事件触发器
所有设备都支持以下常见触发器
- 距离和步数的每日目标
- 步数、距离和持续时间的锻炼目标。
其他设备可能支持更高级的事件触发器。一些示例如下:
- 游泳时计算圈数
- 燃烧卡路里的锻炼目标
- 瞬时速度的锻炼目标
状态
所有设备都支持基本状态功能。状态功能指的是用户当前是否处于活动锻炼中
其他设备可能提供额外的状态功能。一些额外的状态功能包括检测锻炼是否已自动暂停或自动恢复,或者用户何时清醒或入睡。
被动监测中的健康警报
某些设备支持健康警报。这些功能并非所有设备都支持。一些健康警报包括检测心率异常或检测跌倒。
为您推荐
- 注意:当 JavaScript 关闭时,会显示链接文本
- 活动数据和锻炼
- Wear OS 上的健康服务