使用 Google Health API 開發步數體驗

Google Health API 會使用steps間隔資料類型追蹤使用者的步數和活動記錄。步數是每日體能活動的基本指標，可協助開發人員追蹤健身進度、計算能量消耗，以及建立使用者可查看的每日活動摘要。

瞭解如何解讀及建構應用程式中的步數指標，為使用者提供最佳體驗。

支援的資料類型

這個 API 支援下列追蹤步數的資料類型：

表：Google Health API 步數資料類型

資料類型	可用的 作業	範圍
步驟 dataType： steps filter 參數： steps 記錄類型： 間隔 Webhook 支援 支援真正的零 步驟指南 相容裝置 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 健康資料 API 會使用標準公式計算速度和配速：

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

要求中指定的 Accept-Language 標頭會決定距離單位。

每日總覽

如要在旅行、時區變更或日光節約時間期間準確匯總每日步數，請勿執行用戶端時間長度計算。請改為查詢 dailyRollUp 端點，系統會使用世界標準時間偏移量自動調解實體資料缺口。匯總會傳回 StepsRollupValue，其中包含 countSum 欄位，代表要求日期累積的總步數。

繪製使用者介面 (協調)

建構使用者介面元素來顯示步數資料時，請使用 reconcile 端點。如果多個資料來源 (例如智慧手錶和手機) 同時記錄步數，reconcile 端點會解決衝突並合併資料串流，傳回單一的已調解資料串流。

當日追蹤和直方圖

如要顯示全天的詳細使用者活動 (例如圖表)：

• 每小時步數直方圖：查詢 rollUp 端點，並使用 windowSize 參數指定時間長度 (例如 3600s 代表 1 小時)。
• 所有步數記錄：使用 list 端點擷取最精細的原始步數記錄。

rollUp、dailyRollUp 和 reconcile 端點會接受 dataSourceFamily 參數，方便您篩選特定來源群組的資料。如需更多詳細資料和使用範例，請參閱 Endpoints 指南的「依資料來源系列篩選及彙整」一節。

使用 Webhook 即時同步

訂閱 steps 資料類型集合，即可在匯入或同步處理新的步數資料時，即時收到通知。您不必輪詢 REST 端點，而是可以動態更新用戶端資訊主頁，以回應這些 Webhook 通知。如要瞭解如何設定訂閱項目，請參閱Webhook 訂閱項目。

處理真正的零

Google Health API 會實作真正的零，以解決久坐時間間隔。如果使用者配戴追蹤器，但在特定時間內沒有走路，API 會傳回該時間間隔的記錄，其中包含一般資料來源和時間戳記中繼資料，但會省略 count 屬性。

這可讓您區分：

• 靜止不動的佩戴時間：使用者佩戴裝置，但沒有走路。這會傳回沒有 count 屬性的記錄 (解讀為零步)。
• 未佩戴裝置：使用者未佩戴裝置。這會傳回無記錄，導致大量資料缺漏。

詳情請參閱資料存在與實際零值指南。