Wear Health Services (WHS) API 可以為健康與健身應用程式的開發人員提供一致的整合途徑，是所有搭載 Wear OS 3 以上版本裝置的必備元件。建構應用程式時，請確保應用程式可以配合多種裝置和不同功能調整，維持良好的裝置相容性，避免對使用者體驗造成問題。為了達到這個目標，請只針對應用程式使用的用戶端聲明依附元件。另外，也請讓應用程式根據自身適用情形，靈活地顯示或移除選用的進階指標。
各個裝置使用的基礎硬體和感應器平台不同，每種感應器產生資料的頻率也不一樣。舉例來說，某裝置回傳心率的時間戳記可能就和位置資訊不同。因此，請讓應用程式能在不同或重疊的時間戳記接收各自的資料串流。
本指南將說明 Wear Health Services 中各種用戶端支援的資料類型，以及應有的預期行為。
運動用戶端
以下各節將說明 ExerciseClient 的預期行為和資料類型。
預期行為
ExerciseClient 有部分運動類型必須取得特定資料類型才能使用。舉例來說，使用者只能在系統支援推進輪椅的情況下才能執行輪椅相關運動。因此，請按照指定裝置的支援情形啟用/停用這些選項。
大多數的運動資料類型都會以一秒的間隔取樣並傳送，但有些例外：
- 在某些情況下，部分運動資料類型每秒更新的次數不只一次。舉例來說，在使用者執行時，步數更新每秒超過一次。
- 對於部分資料類型，系統只會在當前值和先前值不同時才傳送更新。
傳送資料的方式可以採用串流或批次處理。當應用程式處理器開啟時，系統會串流資料，一般來說這種情況下螢幕也會開啟並可以進行互動。當螢幕關閉或進入微光模式 (開啟中但無法互動)，資料便以批次傳送，以便節省電力。當應用程式處理器因手錶退出微光模式而重新啟動時，或批次處理緩衝區已滿時 (視裝置而定)，系統會將批次處理的資料傳送至應用程式。裝置處於微光模式時，取樣率仍維持不變，因此提供的批次資料仍具有高頻率資料點。
請注意，資料類型只會衍生自手錶上感應器產生的資料。例如位置資料便完全來自手錶，而非手機。
資料類型
利用 ExerciseClient API，您可以開始、暫停、繼續和停止不同類型的健身運動。WHS 會為每種運動定義一組資料類型，這些是系統為該運動類型提供給您使用的類型。這樣做可以節省電力，並簡化應用程式邏輯，因為特定運動不需要的感應器就不會開啟。舉例來說，當使用者開始跑步時，系統只會針對室外的跑步運動提供並追蹤位置資料。使用者開始騎腳踏車運動時，系統就不會提供或追蹤步數。以下各節說明 ExerciseClient 內支援的資料類型。
必要運動資料類型
以下運動資料類型適用於所有裝置。
- 樣本資料類型有對應的 _STATS 資料類型，可以回傳運動的最小值、最大值以及平均值。舉例來說，您可以使用 PACE_STATS 資料類型擷取 PACE 統計資料。
- 間隔資料類型有對應的 _TOTAL 資料類型，可以回傳運動的累積值。舉例來說，您可以使用 DISTANCE_TOTAL 資料類型擷取 DISTANCE 統計資料。
| 指標 | 預期資料 | 預期行為相關備註 |
| 心率 BPM | 每分鐘心跳數 [資料類型：Double] | 運動期間，所有裝置皆會每秒取樣心率一次。部分裝置會每秒回報一項 BPM 值。有些裝置則只會在 BPM 和上次的值不同時才會回報。請不要預期在所有裝置上都會每秒收到一次 BPM 值。 |
| 位置 | 經度和緯度 [資料類型：Double] | 位置資料只會來自手錶的 GPS。請不要預期能從整合式位置預測提供工具或其他 Android 服務取得位置資料。另請注意，每個資料點內也都含有準確率值 (也稱為水平位置錯誤) 和可用性資訊。 |
| 相關步驟 | [資料類型：Long] | 步數是運動期間所跑的總步數，不含暫停運動時的步數。 |
| 距離 | 公尺 [資料類型：Double] | 若有 GPS，系統便會使用 GPS 提供的位置運算，若無 GPS 則用步數計算。總計數值是運動期間的距離總長，不含暫停運動時的部分。 |
| 速度 | [公尺 / 秒] [資料類型：Double] | 回傳最小值、最大值和平均值。這是運動期間的結果，不含暫停運動時的資料。 |
| 步伐 | [秒 / 公尺] [資料類型：Double] | 如果速度為 0，則預設值為 0。平均值是運動期間的結果，不含暫停運動時的資料。 |
| 海電 | 公尺。[資料類型：Double] | 海拔的增加量。總計值是運動期間回報的結果，不含暫停運動時的資料。 |
| TOTAL_CALORIES | 大卡 [資料類型：Double] | 加上基礎代謝率的活動卡路里燃燒量。此處消耗的卡路里會考量使用者在系統設定內指定的身高、體重、年齡及性別，但不考量應用程式收集的任何使用者個人資料。回報的總計數據是運動期間的結果，不含暫停運動時的資料。 |
選用運動資料類型
下列資料類型僅適用於特定裝置。完整資料類型清單請參閱 Jetpack 參考資料。如果某項資料類型未列於上方「必要/保證」清單內，則為選用類型。
請參閱以下選用資料類型示例。請注意，底下僅列出部分示例：
| 指標 | 預期資料 | 預期行為相關備註 |
| 休息 | [資料類型：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 內，並批次傳送給健康照護服務。這些批次處理的結果會根據系統行為，以不同時間間隔回傳。例如在感應器緩衝區已滿，或使用者和螢幕互動時，都可能傳回批次結果。
因此請記得，不是所有資料類型都有預先定義或可預測的批次處理間隔。
被動監控資料類型
| 指標 | 預期資料 | 備忘錄 |
| 心率 BPM | 每分鐘心跳數 [資料類型：Double] | 裝置可能會以不同的間隔回傳心率讀數。部分裝置可能會每秒讀取一次。其他裝置則可能會每十分鐘讀取一次。應用程式無法取得間隔資料，但應妥善因應不同的取樣間隔。 |
| STEPS_DAILY/步 | [資料類型：Long] | 每日步數是距離上次重設以來計算的總步數，WHS 會在午夜觸發重設機制。請注意，運動暫停時的步數也會納入計算。步數則為上次檢查以來的精細差異值。 |
| DISTANCE_DAILY/DISTANCE | 公尺 [資料類型：Double] | 以加速計/步數計算而得。請勿在 GPS 執行期間計算此資訊，這樣才能確保關閉定位服務的使用者依然能收到準確的步數。 |
| 速度 | [公尺 / 秒] [資料類型：Double] | |
| 每天卡路里攝取量 | 大卡 [資料類型：Double] | 一天的卡路里數，包括活動卡路里和 BMR。此處消耗的卡路里數值會考量使用者在系統設定內指定的身高、體重、年齡及性別，不會根據應用程式收集的任何使用者個人資料調整。 |
| RUNNING_STEPS (選用) | [資料類型：Long] | 步數在運動與其他期間的差異值。系統會同時追蹤兩者。 |
| WALKING_STEPS (選用) | [資料類型：Long] | |
| 海電 | 公尺 [資料類型：Double] | 僅含有海拔的正差異值 |
| ELEVATION_LOSS | 公尺 [資料類型：Double] | 僅含有海拔的負差異值 |
| FLOORS_DAILY | [資料類型：Double] | 可表示為「部分」樓層 |
被動監控每日目標
| 指標 | 預期資料 | 備忘錄 |
| STEPS_DAILY | [資料類型：Long] | 每日步數，包括運動暫停時的任何步數。此為自上次重設以來的總步數，由 WHS 在午夜重設。 |
| FLOORS_DAILY | [資料類型：Double] | 可表示為「部分」階梯樓層數。 |
| 每天卡路里攝取量 | 大卡 [資料類型：Double] | 一天內的卡路里，包括活動卡路里及 BMR。 |
| 距離 (每日) | 公尺 [資料類型：Double] | 以加速計或步數計算而得。請勿使用 GPS 計算此資訊，以利關閉定位服務的使用者依然能收到準確的步數資料。 |
| DAILY_ELEVATION_GAIN | 公尺 [資料類型：Double] | 僅含有海拔的正差異值 |
MeasureClient
MeasureClient 用於測量特定時刻的心率。
預期行為
MeasureClient 和 PassiveClient 在某些方面很像。兩者都提供非批次且和運動無關聯的健康統計資料。您可以同時使用這兩種語言測量心率，但主要差別在於 MeasureClient 包含心率資料可用性，但 PassiveClient 並未提供供應情形資訊。
資料類型
| 指標 | 預期資料 | 備忘錄 |
| 心率 BPM | 每分鐘心跳數 [資料類型：Double] | 也包括可用性資訊。 |
支援的功能
除了運動資料類型和被動監控資料類型外，裝置也支援用於觸發事件的其他功能，例如開始運動以及測量狀態 (像是睡眠與清醒)。其中某些是所有裝置皆支援的功能，有些則只在部分裝置提供。
事件觸發條件
所有裝置皆可支援以下常見的觸發條件：
- 每日距離和步數目標
- 運動步數、距離和時長目標。
其他裝置可能還支援更進階的事件觸發條件。以下提供幾個範例：
- 計算游泳趟數
- 卡路里燃燒量運動目標
- 瞬時速度的運動目標
狀態
所有裝置皆可支援基本狀態功能。此功能可指出使用者目前是否正在運動。
其他裝置可能會提供一些額外的狀態功能，例如偵測運動是否已經自動暫停或自動繼續，或是使用者是否正在睡覺。
被動監控的健康警示
部分裝置支援健康警示，並非所有裝置都支援這些功能。健康警示包括偵測心率是否異常或偵測是否摔倒等。
為您推薦
- 注意：系統會在 JavaScript 關閉時顯示連結文字
- 活動資料與運動
- Wear OS 上的健康照護服務