Migliora la compatibilità delle app su tutti i dispositivi Wear OS

L'API Wear Health Services (WHS) è un componente obbligatorio per tutti i dispositivi che eseguono Wear OS 3 e versioni successive, in quanto fornisce una superficie di integrazione coerente per gli sviluppatori di app per la salute e il fitness. Crea la tua app in modo che si adatti facilmente a molti dispositivi e alle loro diverse funzionalità per mantenere la compatibilità tra i dispositivi ed evitare problemi di esperienza utente. Per farlo, dichiara le dipendenze solo per i client utilizzati dalla tua app. Inoltre, consenti alla tua app di visualizzare o rimuovere le metriche avanzate facoltative in base alla loro disponibilità.

Sensori diversi generano dati a frequenze diverse che variano in base al dispositivo in base all'hardware e alla piattaforma di sensori sottostanti. Ad esempio, un dispositivo potrebbe restituire la frequenza cardiaca a un timestamp e la posizione a un altro. Crea app che possono ricevere flussi di dati indipendenti con timestamp diversi o sovrapposti.

Questa guida descrive i comportamenti previsti e i tipi di dati supportati da vari client all'interno di Wear Health Services.

Client di esercizio

Le sezioni seguenti descrivono i comportamenti e i tipi di dati previsti per ExerciseClient.

Comportamenti previsti

Per ExerciseClient, alcuni tipi di allenamento dipendono dalla disponibilità di determinati tipi di dati. Ad esempio, gli esercizi in sedia a rotelle sono disponibili solo se sono supportate le spinte della sedia a rotelle. Attiva e disattiva queste opzioni in base alla loro disponibilità su un determinato dispositivo.

La maggior parte dei tipi di dati di allenamento vengono campionati e forniti a intervalli di un secondo, con alcune eccezioni:

  • In alcune situazioni, alcuni tipi di dati di allenamento vengono aggiornati più di una volta al secondo. Ad esempio, quando l'utente corre, il conteggio dei passi viene aggiornato più di una volta al secondo.
  • Per alcuni tipi di dati, un aggiornamento viene fornito solo se il valore attuale è diverso dal valore precedente.

La distribuzione dei dati può essere in streaming o in batch. I dati vengono trasmessi in streaming mentre il processore dell'applicazione è attivo, ovvero in genere quando il display è acceso e interattivo. Una volta che il display si spegne o entra in modalità Ambient (acceso ma non interattivo), i dati vengono raggruppati per risparmiare energia. I dati batch vengono inviati all'applicazione quando il processore dell'applicazione si riaccende, perché lo smartwatch esce dalla modalità Ambient o quando i buffer per il batch sono pieni, il che varia in base al dispositivo. La frequenza di campionamento rimane la stessa mentre il dispositivo è in modalità Ambient, quindi un batch consegnato contiene ancora punti dati ad alta frequenza.

I tipi di dati derivano esclusivamente dai dati generati dai sensori dello smartwatch. Ad esempio, i dati sulla posizione provengono interamente dallo smartwatch e non dallo smartphone.

Tipi di dati

L'API ExerciseClient consente di avviare, mettere in pausa, riprendere e interrompere gli allenamenti di diversi tipi. Per ogni allenamento, WHS definisce un insieme di tipi di dati che vengono resi disponibili per quel tipo di allenamento. In questo modo si risparmia energia e si semplifica la logica dell'app, in quanto i sensori non necessari per un determinato allenamento non vengono attivati. Ad esempio, quando inizi una corsa, i dati sulla posizione vengono forniti e monitorati solo per una corsa all'aperto. Quando inizi un allenamento in bici, i passi non vengono forniti o monitorati. Le seguenti sezioni forniscono una descrizione dei tipi di dati supportati in ExerciseClient.

Tipi di dati di allenamento disponibili su tutti i dispositivi

I seguenti tipi di dati di allenamento sono disponibili su tutti i dispositivi.

  • I tipi di dati di esempio hanno un tipo di dati _STATS corrispondente che restituisce i valori minimo, massimo e medio dell'esercizio. Ad esempio, le statistiche PACE possono essere estratte con il tipo di dati PACE_STATS.
  • I tipi di dati intervallo hanno un tipo di dati _TOTAL corrispondente che restituisce il valore cumulativo dell'esercizio. Ad esempio, le statistiche DISTANCE possono essere estratte con il tipo di dati DISTANCE_TOTAL.
Tabella 1: tipi di dati di allenamento disponibili su tutti i dispositivi
Metrica Dati previsti Note sui comportamenti previsti
HEART_RATE_BPM Battiti al minuto [DataType: Double] Tutti i dispositivi campionano il battito cardiaco una volta al secondo durante un allenamento. Alcuni dispositivi segnalano un valore di battiti al minuto ogni secondo. Alcuni dispositivi segnalano i battiti al minuto solo quando sono cambiati rispetto al valore precedente. Non aspettarti di ricevere un valore BPM a intervalli di un secondo su tutti i dispositivi.
LOCALITÀ Latitudine e longitudine [Tipo di dati: Double] I dati sulla posizione si basano solo sul GPS dello smartwatch. Non aspettarti che i dati sulla posizione provengano dal Fused Location Provider o da altri servizi Android. Ogni punto dati include anche un valore di precisione (noto anche come errore di posizione orizzontale) e disponibilità.
PASSAGGI [Tipo di dati: Long] Il conteggio dei passi è un totale progressivo per tutta la durata dell'allenamento, non incluso il tempo in cui l'allenamento è in pausa
DISTANZA Metri [Tipo di dati: Double] Calcolata in base alla posizione GPS, se disponibile, e in base ai passi in caso contrario. Totale si riferisce al totale per tutta la durata dell'esercizio, non incluso il tempo in cui l'esercizio è in pausa.
VELOCITÀ [metri / secondo] [Tipo di dati: Double] Restituisce i valori minimo, massimo e medio. Questi valori si riferiscono alla durata dell'allenamento, escluso il tempo in cui l'allenamento è in pausa.
PACE [secondi / metro] [Tipo di dati: Double] Il valore predefinito è 0 se la velocità è 0. Le medie si riferiscono alla durata dell'allenamento, escluso il tempo in cui l'allenamento è in pausa.
ELEVATION_GAIN Metri. [Tipo di dati: Double] Variazioni di elevazione positive. Il totale viene riportato per tutta la durata dell'esercizio, escluso il tempo in cui l'esercizio è in pausa.
TOTAL_CALORIES kCal [Tipo di dati: Double] Calorie bruciate durante l'attività fisica aggiunte al tasso metabolico basale. Le calorie emesse qui tengono conto di altezza, peso, età e genere dell'utente come specificato nelle impostazioni di sistema. Le calorie non tengono conto dei dati del profilo utente raccolti nella tua app. Il totale riportato si riferisce alla durata dell'allenamento, escluso il tempo in cui l'allenamento è in pausa.

Tipi di dati facoltativi per l'esercizio

Il seguente elenco di tipi di dati è disponibile solo su alcuni dispositivi. Consulta il riferimento Jetpack per un elenco completo di DataTypes. Se un DataType non è presente nell'elenco precedente "obbligatorio/garantito", è facoltativo.

Vedi i seguenti esempi di tipi di dati facoltativi. Questo elenco non è completo:

Tabella 2: esempi di tipi di dati di esercizi facoltativi
Metrica Dati previsti Note sui comportamenti previsti
ABSOLUTE_ELEVATION [Tipo di dati: Double]
ELEVATION_LOSS Metri [Tipo di dati: Double] Variazioni negative di elevazione. Il valore è positivo. Ad esempio, una perdita di elevazione di 1 metro viene restituita come 1, non -1.
STEPS_PER_MINUTE [Tipo di dati: Long]
WHEELCHAIR_PUSHES [Tipo di dati: Long] Un conteggio delle spinte della sedia a rotelle da utilizzare negli esercizi basati sulla sedia a rotelle.
REP_COUNT [Tipo di dati: Long]
SWIM_STROKE_COUNT [Tipo di dati: Long]
SWIM_LAP_COUNT [Tipo di dati: Long]

Tipi di dati per esercizio

Per ogni tipo di allenamento vengono restituiti diversi tipi di dati. I tipi di dati restituiti sono coerenti con le esigenze dell'esercizio. Ad esempio, il tipo di esercizio CICLISMO non restituisce il tipo di dati PASSI. Utilizza il metodo Capabilities in fase di runtime per determinare quali tipi di dati sono supportati sul dispositivo dell'utente.

Come minimo, tutti i tipi di allenamento restituiscono dati relativi a battito cardiaco e calorie. Altri allenamenti potrebbero supportare tipi di dati aggiuntivi, a seconda dei requisiti dell'allenamento.

Ecco alcuni esempi:

  • Esercizi come la meditazione o il pilates supportano solo il battito cardiaco e le calorie
  • Allenamenti come basket o badminton supportano battito cardiaco, calorie, distanza e passi.
  • Esercizi come camminata e corsa supportano frequenza cardiaca, calorie, distanza, passi, velocità e andatura
  • Il nuoto supporta il battito cardiaco, le calorie, la distanza e le vasche

Client di monitoraggio passivo

I seguenti tipi di dati sono obbligatori per tutti i dispositivi con Wear OS per supportare le app che monitorano passivamente i dati su salute e fitness, come la frequenza cardiaca
e il numero di passi. Ciascuno di questi tipi di dati deve essere derivato esclusivamente dai dati generati dai sensori dello smartwatch.

Comportamenti previsti

Per risparmiare energia, le letture dei sensori ottenute tramite il monitoraggio passivo vengono memorizzate sulla MCU e raggruppate in batch per i servizi sanitari. Questi risultati batch vengono restituiti a intervalli diversi a seconda del comportamento del sistema. Alcuni esempi includono la restituzione di batch quando i buffer dei sensori sono pieni o quando l'utente interagisce con il display.

Non presupporre intervalli di batching predefiniti o prevedibili per nessun tipo di dati.

Tipi di dati di monitoraggio passivo

Tabella 3: tipi di dati di monitoraggio passivo richiesti per i dispositivi Wear OS
Metrica Dati previsti Notes
HEART_RATE_BPM Battiti al minuto [Tipo di dati: Double] I dispositivi potrebbero restituire letture del battito cardiaco a intervalli diversi. Alcuni dispositivi potrebbero richiedere una lettura al secondo. Altri dispositivi potrebbero effettuare una lettura ogni dieci minuti. Questi intervalli non vengono resi disponibili alle app. Le app devono adattarsi correttamente a intervalli di campionamento diversi.
STEPS_DAILY/STEPS [Tipo di dati: Long] Passi giornalieri è il numero totale di passi effettuati dall'ultimo azzeramento, che viene attivato da WHS a mezzanotte. Sono inclusi i passi effettuati mentre un allenamento attivo è in pausa. I passaggi sono una differenza granulare rispetto all'ultimo controllo.
DISTANCE_DAILY/DISTANCE metri [Tipo di dati: Double] Calcolato in base ad Accelerometro/Passi. Non eseguire calcoli durante il GPS per garantire che gli utenti che hanno disattivato i servizi di localizzazione possano comunque ricevere conteggi dei passi accurati.
VELOCITÀ [metri / secondo] [Tipo di dati: Double]
CALORIES_DAILY kCal [Tipo di dati: Double] Calorie per la giornata, incluse le calorie attive e il BMR. La cifra delle calorie emessa qui tiene conto di altezza, peso, età e genere dell'utente specificati nelle impostazioni di sistema. Le calorie non vengono regolate in base ai dati del profilo utente raccolti nella tua app.
RUNNING_STEPS (facoltativo) [Tipo di dati: Long] Delta dei passi sia durante un allenamento che in altre situazioni. Monitora entrambi contemporaneamente.
WALKING_STEPS (facoltativo) [Tipo di dati: Long]
ELEVATION_GAIN metri [Tipo di dati: Double] Include solo i delta positivi di elevazione
ELEVATION_LOSS metri [Tipo di dati: Double] Include solo i delta negativi di elevazione
FLOORS_DAILY [Tipo di dati: Double] Possono essere rappresentati come piani "parziali"

Obiettivi giornalieri di monitoraggio passivo

Tabella 4: Metriche degli obiettivi giornalieri di monitoraggio passivo
Metrica Dati previsti Notes
STEPS_DAILY [Tipo di dati: Long] I passi giornalieri, inclusi quelli effettuati mentre un allenamento attivo è in pausa, sono il numero totale di passi effettuati dall'ultimo ripristino. WHS si azzera a mezzanotte.
FLOORS_DAILY [Tipo di dati: Double] Possono essere rappresentati come piani "parziali" di scale.
CALORIES_DAILY kCal [Tipo di dati: Double] Calorie per la giornata, che includono le calorie attive e il BMR.
DISTANCE_DAILY metri [Tipo di dati: Double] Calcolato in base all'accelerometro o al conteggio dei passi. Non calcolare questo valore utilizzando il GPS, in modo che gli utenti che hanno disattivato i servizi di localizzazione possano comunque ricevere conteggi dei passi accurati.
DAILY_ELEVATION_GAIN metri [Tipo di dati: Double] Include solo i delta positivi di elevazione

MeasureClient

Utilizza MeasureClient per misurare la frequenza cardiaca in un determinato momento.

Comportamenti previsti

MeasureClient e PassiveClient sono simili per alcuni aspetti. Entrambi forniscono statistiche sulla salute non batch correlate a un allenamento. Puoi utilizzare entrambi per misurare la frequenza cardiaca, ma la differenza principale è che MeasureClient include la disponibilità dei dati sulla frequenza cardiaca, mentre PassiveClient non include le informazioni sulla disponibilità.

Tipi di dati

Tabella 5: tipi di dati MeasureClient
Metrica Dati previsti Notes
HEART_RATE_BPM Battiti al minuto [Tipo di dati: Double] Include anche la disponibilità

Funzionalità supportate

Oltre ai tipi di dati di allenamento e di monitoraggio passivo, i dispositivi supportano funzionalità aggiuntive per attivare eventi come l'inizio di un allenamento e misurare lo stato, ad esempio se stai dormendo o sei sveglio. Alcune di queste funzionalità sono disponibili su tutti i dispositivi, mentre altre solo su alcuni.

Trigger evento

Tutti i dispositivi supportano i seguenti trigger comuni:

  • Obiettivi giornalieri per distanza e passi
  • Obiettivi di allenamento per passi, distanza e durata.

Altri dispositivi potrebbero supportare trigger di eventi più avanzati. Alcuni esempi includono i seguenti:

  • Conteggio delle vasche durante il nuoto
  • Obiettivi di allenamento per le calorie bruciate
  • Obiettivi di allenamento per la velocità istantanea

Stati

Tutti i dispositivi supportano la funzionalità di stato di base. La funzionalità di stato si riferisce al fatto che un utente stia svolgendo o meno un esercizio attivo.

Altri dispositivi potrebbero fornire funzionalità di stato aggiuntive. Alcune funzionalità aggiuntive dello stato includono il rilevamento dell'interruzione automatica o della ripresa automatica di un allenamento oppure quando l'utente è sveglio o dorme.

Avvisi salute nel monitoraggio passivo

Alcuni dispositivi supportano gli avvisi per la salute. Queste funzionalità non sono supportate su tutti i dispositivi. Alcuni avvisi per la salute includono il rilevamento di anomalie del battito cardiaco o il rilevamento di cadute.