使用 Google Health API 開發步數體驗

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

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

支援的資料類型

API 支援下列資料類型，可用於追蹤步數：

表格：Google Health API 步數資料類型

資料類型	可用的 作業	範圍
步驟 dataType: steps filter 參數： steps 記錄類型： 間隔 儲存空間解析度： 1 分鐘 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 端點，該端點會使用世界標準時間偏移量自動協調實體資料落差。匯總會傳回包含 countSum 欄位的 StepsRollupValue，代表指定日期累積的總步數。詳情請參閱「匯總資料」指南中的「匯總日曆天數」一節。

繪製使用者介面 (協調)

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

如要瞭解如何處理連結裝置同步作業和時間戳記可變性造成的重疊時間間隔，請參閱資料管理指南。

當日追蹤和直方圖

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

• 每小時或每分鐘步數直方圖：查詢 rollUp 端點，並使用 windowSize 參數指定時間長度 (例如 60s 代表 1 分鐘，3600s 代表 1 小時)。由於步數資料是以 1 分鐘 (60s) 為間隔記錄，因此請將 windowSize 設為至少 60s。如果要求的時間範圍小於一分鐘 (例如 10s 或 30s)，系統不會分割每分鐘的總計，而是將整分鐘的計數放入第一個相符的子值區。詳情請參閱「匯總時間範圍和儲存空間解析度」。
• 所有步數記錄：使用 list 端點擷取最精細的原始步數記錄。

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

使用 Webhook 即時同步

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