使用 Google Health API 开发步数体验

Google Health API 使用 steps 时间间隔数据类型跟踪用户的步数和活动数据。步数是衡量每日身体活动的基本指标，有助于开发者跟踪健身进度、计算能量消耗，以及构建面向用户的每日活动摘要。

了解如何在应用中读取和构建步数指标，以便为用户提供最佳体验。

支持的数据类型

该 API 支持以下数据类型来跟踪步数：

表：Google Health API 步数数据类型

数据类型	可用 操作	范围
步数 dataType： steps 过滤条件参数： steps 记录类型： Interval Webhook 支持 True zeros 支持 步数指南 兼容的设备 Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list、reconcile、rollup、dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

指南

将步数跟踪功能集成到应用时，请遵循以下设计和实现指南。

速度和配速计算

Google Health API 使用标准公式来计算速度和配速：

• 速度 = distance / time(hour)
• 配速 = time(seconds) / distance

请求中指定的 Accept-Language 标头决定了距离单位。

每日概览

为了在旅行、时区变更或夏令时期间准确汇总每日步数，请勿执行客户端时长计算。请改为查询 dailyRollUp 端点，该端点会使用 UTC 偏移量自动协调实际数据缺口。汇总会返回一个 StepsRollupValue，其中包含 countSum 字段，表示所请求日期的累计步数总和。

绘制界面（协调）

构建用于显示步数数据的界面元素时，请使用 reconcile 端点。如果多个数据源（例如智能手表和手机）同时记录了步数，reconcile 端点会解决冲突并合并数据流，以返回单个协调的数据流。

日内跟踪和直方图

如需显示全天的详细用户活动（例如图表和图形）：

• 每小时步数直方图： 查询 rollUp 端点，并使用 windowSize 参数指定时长（例如 3600s 表示 1 小时）。
• 所有步数记录： 使用 list 端点提取最精细的原始步数记录。

rollUp、dailyRollUp 和 reconcile 端点接受 dataSourceFamily 参数，以便您过滤来自特定来源组的数据。如需了解详情和使用示例，请参阅端点指南的 按数据源系列过滤和汇总 部分。

使用 Webhook 进行实时同步

订阅 steps 数据类型集合，以便在新步数数据导入或同步时获得实时通知。您可以动态更新客户端信息中心，以响应这些 Webhook 通知，而不是轮询 REST 端点。如需详细了解如何设置订阅，请参阅 Webhook 订阅。

处理 True zeros

Google Health API 会实现 True zeros 来解决久坐时间间隔。如果用户在给定时间段内佩戴了跟踪器但没有行走，API 会返回该时间间隔的记录，其中包含正常的数据源和时间戳元数据，但会省略 count 属性。

这样，您就可以区分以下情况：

• 静止佩戴时间段： 用户佩戴了设备但没有行走。这会返回不含 count 属性的记录（解释为零步）。
• 未佩戴时间段： 用户未佩戴设备。这不会返回任何记录，导致出现较大的数据缺口。

如需了解详情，请参阅 数据存在性和 True zeros 指南。