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