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

L'API Wear Health Services (WHS) è un componente obbligatorio per tutti i dispositivi con Wear OS 3 e versioni successive, in quanto fornisce una piattaforma di integrazione coerente per gli sviluppatori di servizi di salute e fitness. Crea la tua app per adattarla agevolmente a più dispositivi e alle loro diverse funzionalità, in modo da mantenere la compatibilità tra dispositivi ed evitare problemi con l'esperienza utente. A questo scopo, dichiara le dipendenze solo per i client utilizzati dalla tua app. Inoltre, offri alla tua app la flessibilità di visualizzare o rimuovere metriche avanzate facoltative in base alla loro disponibilità.

Sensori diversi generano dati a frequenze diverse che variano per dispositivo in base all'hardware e alla piattaforma dei sensori sottostanti. Ad esempio, un dispositivo potrebbe restituire il battito cardiaco a un timestamp e posizione in un altro. Crea app in grado di ricevere stream di dati indipendenti con timestamp diversi o in corrispondenza di timestamp sovrapposti.

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

Client allenamento

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

Comportamenti previsti

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

La maggior parte dei tipi di dati di allenamento viene campionata e pubblicata 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 è in esecuzione, il conteggio dei passi viene aggiornato più di una volta al secondo.
  • Per alcuni tipi di dati, un aggiornamento viene eseguito solo se il valore attuale è diverso dal valore precedente.

L'invio dei dati può essere in modalità flusso o batch. I dati vengono trasmessi in streaming mentre il processore delle applicazioni è attivo, ovvero in genere quando il display è attivo e interattivo. Quando il display si spegne o entra in modalità Ambient (acceso ma non interattivo), i dati vengono raggruppati per risparmiare energia. I dati in 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 esauriti, il che varia a seconda del dispositivo. La frequenza di campionamento rimane la stessa mentre il dispositivo è in modalità Ambient, quindi un batch pubblicato ha ancora punti dati ad alta frequenza.

I tipi di dati derivano esclusivamente dai dati generati dai sensori sull'orologio. Ad esempio, i dati sulla posizione provengono interamente dall'orologio e non dal telefono.

Tipi di dati

L'API ExerciseClient ti consente di avviare, sospendere, riprendere e interrompere esercizi di diversi tipi. Per ogni esercizio, WHS definisce un insieme di tipi di dati che vengono resi disponibili per ogni tipo di esercizio. Questo consente di risparmiare energia e semplifica la logica dell'app, poiché i sensori non necessari per un determinato esercizio non sono 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 garantiti

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 ricavate con il tipo di dati PACE_STATS.
  • I tipi di dati relativi all'intervallo hanno un tipo di dati _TOTAL corrispondente che restituisce il valore cumulativo dell'esercizio. Ad esempio, le statistiche di DISTANZA possono essere ricavate con il tipo di dati DISTANZA_TOTAL.
Metrica Dati previsti Note sui comportamenti previsti
HEART_RATE_B/M Battiti al minuto [Tipo di dati: doppio] Tutti i dispositivi campionano il battito cardiaco una volta al secondo durante un allenamento. Alcuni dispositivi segnalano un valore B/M ogni secondo. Alcuni dispositivi segnalano i b/m solo quando sono cambiati rispetto al valore precedente. Non aspettarti di ricevere un valore B/M a ogni intervallo di un secondo su tutti i dispositivi.
LOCALITÀ Latitudine e longitudine [Tipo di dati: doppia] I dati sulla posizione sono basati soltanto sul GPS dell'orologio. Non aspettarti che i dati sulla posizione provengano da 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 la disponibilità.
PASSAGGI [Tipo di dati: lungo] Il conteggio dei passi corrisponde al totale della corsa per la durata dell'allenamento, escluso il tempo in cui l'allenamento è sospeso
DISTANZA Metri [Tipo di dati: Doppio] Calcolata dalla posizione basata sul GPS, se disponibile, e dai passi negli altri casi. Totale si riferisce al totale per l'intera durata dell'allenamento, escluso il tempo in cui l'allenamento viene sospeso.
VELOCITÀ [metri / secondo] [Tipo di dati: Doppio] Restituisce i valori minimo, massimo e medio. Questi valori coprono la durata dell'allenamento, escluso il tempo in cui l'allenamento è in pausa.
RITMO [secondi / metro] [Tipo di dati: Doppio] Il valore predefinito è 0 se la velocità è 0. Le medie si riferiscono all'intera durata dell'allenamento, escluso il tempo in cui l'allenamento è stato sospeso.
AUMENTO_ALTITUDINE Metri. [Tipo di dati: Doppio] Cambi di altitudine positivi. Il totale viene riportato per l'intera durata dell'allenamento, escluso il tempo in cui l'allenamento viene sospeso.
TOTAL_CALORIES kCal [Tipo di dati: doppio] Calorie bruciate durante l'attività fisica aggiunte al tasso metabolico basale. Le calorie emesse qui prendono in considerazione l'altezza, il peso, l'età e il genere dell'utente, come specificato nelle impostazioni di sistema. Le calorie non prendono in considerazione i dati del profilo utente raccolti nella tua app. Il totale riportato corrisponde all'intera durata dell'allenamento, escluso il tempo in cui l'allenamento è in pausa.

Tipi di dati di allenamento facoltativi

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

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

Metrica Dati previsti Note sui comportamenti previsti
ELEVAZIONE_ABSOLUTO [Tipo di dati: Doppio]
PERDITA_ALTITUDINE Metri [Tipo di dati: Doppio] Cambiamenti di altitudine negativi. Il valore è positivo. Ad esempio, una perdita di altitudine di 1 m viene restituita come 1, non -1.
PASSI_PER_MINUTO [Tipo di dati: lungo]
PUSH_SEDIA_RUOTE [Tipo di dati: lungo] Un conteggio di spinte in sedia a rotelle da utilizzare per allenamenti in sedia a rotelle.
REP_COUNT [Tipo di dati: lungo]
NUOVI_STROKE_COUNT [Tipo di dati: lungo]
NUOVI_LAP_COUNT [Tipo di dati: lungo]

Tipi di dati per allenamento

Vengono restituiti diversi tipi di dati per ogni tipo di allenamento. I tipi di dati che vengono restituiti sono coerenti con le esigenze dell'esercizio. Ad esempio, il Tipo di allenamento BIKING non restituisce il tipo di dati STEPS. 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 su battito cardiaco e calorie. Altri esercizi potrebbero supportare tipi di dati aggiuntivi, a seconda dei requisiti dell'esercizio.

Ecco alcuni esempi:

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

Client di monitoraggio passivo

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

Comportamenti previsti

Per risparmiare energia, le letture dei sensori ottenute mediante il monitoraggio passivo vengono archiviate nell'MCU e raggruppate in Health Services. Questi risultati raggruppati vengono restituiti a intervalli diversi a seconda del comportamento del sistema. Alcuni esempi includono la restituzione di batch quando i buffer del sensore sono pieni o quando l'utente interagisce con il display.

Non presupporre intervalli di batch predefiniti o prevedibili per qualsiasi tipo di dati.

Tipi di dati di monitoraggio passivo

Metrica Dati previsti Notes
HEART_RATE_B/M Battiti al minuto [Tipo di dati: Doppio] I dispositivi possono restituire letture della frequenza cardiaca a intervalli diversi. Alcuni dispositivi potrebbero richiedere letture ogni secondo. Altri dispositivi potrebbero eseguire una lettura ogni dieci minuti. Questi intervalli non vengono resi disponibili alle app. Le app dovrebbero adattarsi agevolmente a diversi intervalli di campionamento.
PASSI_GIORNALIERI/PASSI [Tipo di dati: lungo] Passi giornalieri è il numero totale di passi effettuati dall'ultimo ripristino, che viene attivato dalla WHS a mezzanotte. Sono inclusi i passi effettuati mentre un allenamento attivo è sospeso. I passaggi sono un delta granulare dall'ultimo controllo.
DISTANZA_GIORNALIERA/DISTANZA metri [Tipo di dati: Doppio] Calcolato da accelerometro/passi. Non effettuare calcoli durante il GPS per garantire che gli utenti che hanno disattivato i servizi di geolocalizzazione possano comunque ricevere un conteggio dei passi accurato.
VELOCITÀ [metri / secondo] [Tipo di dati: Doppio]
CALORIE_GIORNALIERE kCal [Tipo di dati: doppio] Calorie per la giornata, incluse calorie attive e metabolismo basale. Il valore delle calorie emesse qui prende in considerazione l'altezza, il peso, l'età e il genere dell'utente, come specificato nelle impostazioni di sistema. Le calorie non vengono modificate in base ai dati del profilo utente raccolti nella tua app.
RUNNING_STEPS (facoltativo) [Tipo di dati: lungo] Delta dei passi sia durante un allenamento che nelle altre. Monitora entrambi contemporaneamente.
WALKING_STEPS (facoltativo) [Tipo di dati: lungo]
AUMENTO_ALTITUDINE metri [Tipo di dati: Doppio] Include solo i delta positivi in altitudine
PERDITA_ALTITUDINE metri [Tipo di dati: Doppio] Include solo i delta negativi in altitudine
PIANI_GIORNALIERI [Tipo di dati: Doppio] Possono essere rappresentati come prezzi "parziali"

Monitoraggio passivo degli obiettivi giornalieri

Metrica Dati previsti Notes
PASSI_GIORNALIERI [Tipo di dati: lungo] I passi giornalieri, inclusi i passi effettuati mentre un allenamento attivo è sospeso, è il numero totale di passi effettuati dall'ultimo ripristino. Il WHS viene reimpostato a mezzanotte.
PIANI_GIORNALIERI [Tipo di dati: Doppio] Possono essere rappresentati come piani "parziali" di scale.
CALORIE_GIORNALIERE kCal [Tipo di dati: doppio] Calorie per la giornata, incluse calorie attive e metabolismo basale.
DISTANZA_GIORNALIERO metri [Tipo di dati: Doppio] Calcolato dall'accelerometro o dal conteggio dei passi. Non calcolarlo utilizzando il GPS, in modo che gli utenti che hanno disattivato i servizi di geolocalizzazione possano comunque ricevere un conteggio dei passi accurato.
GUADAGNO_DI_ELEVAZIONE_GIORNALIERA metri [Tipo di dati: Doppio] Include solo i delta positivi in altitudine

MisuraCliente

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

Comportamenti previsti

MeasureClient e PassiveClient sono simili per alcuni aspetti. Entrambi forniscono statistiche di salute non batch non 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, ma PassiveClient non include informazioni sulla disponibilità.

Tipi di dati

Metrica Dati previsti Notes
HEART_RATE_B/M Battiti al minuto [Tipo di dati: Doppio] Include anche la disponibilità

Funzionalità supportate

Oltre ai tipi di dati relativi all'allenamento e ai tipi di dati per il monitoraggio passivo, i dispositivi supportano funzionalità aggiuntive per attivare eventi come l'avvio di un allenamento e la misurazione dello stato, come sonno o veglia. Alcune di queste funzioni sono disponibili su tutti i dispositivi, mentre altre sono disponibili solo su alcuni.

Trigger di eventi

Tutti i dispositivi supportano i seguenti attivatori comuni:

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

Altri dispositivi potrebbero supportare attivatori di eventi più avanzati. Tra gli esempi di tali prodotti o servizi figurano:

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

Stati

Tutti i dispositivi supportano la funzionalità di base dello stato. La funzionalità di stato indica se un utente sta attualmente facendo un esercizio attivo o meno

Altri dispositivi potrebbero fornire funzionalità di stato aggiuntive. Alcune funzionalità aggiuntive per lo stato includono il rilevamento di un allenamento messo in pausa o ripristinato automaticamente oppure quando l'utente è sveglio o addormentato.

Avvisi di salute nel monitoraggio passivo

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