加強 Wear OS 裝置的應用程式相容性

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] 也包括可用性資訊。

支援的功能

除了運動資料類型和被動監控資料類型外，裝置也支援用於觸發事件的其他功能，例如開始運動以及測量狀態 (像是睡眠與清醒)。其中某些是所有裝置皆支援的功能，有些則只在部分裝置提供。

事件觸發條件

所有裝置皆可支援以下常見的觸發條件：

  • 每日距離和步數目標
  • 運動步數、距離和時長目標。

其他裝置可能還支援更進階的事件觸發條件。以下提供幾個範例：

  • 計算游泳趟數
  • 卡路里燃燒量運動目標
  • 瞬時速度的運動目標

狀態

所有裝置皆可支援基本狀態功能。此功能可指出使用者目前是否正在運動。

其他裝置可能會提供一些額外的狀態功能，例如偵測運動是否已經自動暫停或自動繼續，或是使用者是否正在睡覺。

被動監控的健康警示

部分裝置支援健康警示，並非所有裝置都支援這些功能。健康警示包括偵測心率是否異常或偵測是否摔倒等。