Większa zgodność aplikacji na urządzeniach z Wear OS

Interfejs Wear Health Services API (WHS) jest obowiązkowym komponentem wszystkich urządzeń z Wear OS 3 i nowszym, ponieważ zapewnia spójny interfejs integracji dla deweloperów aplikacji do dbania o zdrowie i kondycję. Zaprojektuj aplikację tak, aby dobrze dostosowywała się do wielu urządzeń i ich różnych możliwości. Dzięki temu zachowasz kompatybilność na różnych urządzeniach i unikniesz problemów z użytkowaniem. Aby to zrobić, zadeklaruj zależności tylko w przypadku klientów, z których korzysta Twoja aplikacja. Dodatkowo zezwól aplikacji na wyświetlanie lub usuwanie opcjonalnych danych zaawansowanych w zależności od ich dostępności.

Różne czujniki generują dane z różną częstotliwością, która zależy od urządzenia, sprzętu i platformy czujnika. Na przykład urządzenie może zwrócić tętno w jednej sygnaturze czasowej, a lokalizację w innej. Twórz aplikacje, które mogą odbierać niezależne strumienie danych z różnymi sygnaturami czasowymi lub z sygnaturami czasowymi, które się pokrywają.

Ten przewodnik opisuje oczekiwane zachowania i typy danych obsługiwane przez różne klienty w ramach Usług zdrowotnych na Wear.

Klient wykonawczy

W sekcjach poniżej opisujemy oczekiwane zachowania i typy danych ExerciseClient.

Oczekiwane zachowania

W przypadku ExerciseClient niektóre typy ćwiczeń zależą od dostępności określonych typów danych. Na przykład ćwiczenia na wózku inwalidzkim są dostępne tylko wtedy, gdy obsługiwane są pchnięcia wózka. Włączaj i wyłączaj te opcje w zależności od ich dostępności na danym urządzeniu.

Większość typów danych o aktywności jest próbkowana i dostarczana w interwałach 1-sekundowych, z wyjątkiem:

  • W niektórych sytuacjach niektóre typy danych o aktywności są aktualizowane częściej niż raz na sekundę. Na przykład, gdy użytkownik biegnie, liczba kroków jest aktualizowana częściej niż raz na sekundę.
  • W przypadku niektórych typów danych aktualizacja jest dostarczana tylko wtedy, gdy bieżąca wartość różni się od poprzedniej.

Dane mogą być dostarczane strumieniowo lub w pakietach. Dane są przesyłane strumieniowo, gdy procesor aplikacji jest włączony, czyli zwykle wtedy, gdy wyświetlacz jest włączony i interaktywny. Gdy wyświetlacz się wyłączy lub przejdzie w tryb nieaktywny (włączony, ale nieinteraktywny), dane są przetwarzane w pakietach, aby oszczędzać energię. Dane w pakietach są dostarczane do aplikacji, gdy procesor aplikacji ponownie się włączy (np. gdy zegarek wyjdzie z trybu otoczenia) lub gdy bufory pakietowania są pełne (zależy to od urządzenia). Częstotliwość próbkowania pozostaje taka sama, gdy urządzenie jest w trybie otoczenia, więc dostarczana partia nadal zawiera punkty danych o wysokiej częstotliwości.

Typy danych pochodzą wyłącznie z danych generowanych przez czujniki na zegarku. Na przykład dane o lokalizacji pochodzą w całości z zegarka, a nie z telefonu.

Typy danych

Interfejs ExerciseClient API umożliwia rozpoczynanie, wstrzymywanie, wznawianie i zatrzymywanie treningów różnych typów. W przypadku każdego ćwiczenia WHS określa zestaw typów danych, które są udostępniane w przypadku danego rodzaju ćwiczenia. Pozwala to oszczędzać energię i upraszcza logikę aplikacji, ponieważ czujniki, które nie są potrzebne do danego ćwiczenia, nie są włączane. Na przykład podczas rozpoczynania biegu dane o lokalizacji są podawane i śledzone tylko w przypadku biegu na zewnątrz. Podczas rozpoczynania ćwiczenia na rowerze kroki nie są podawane ani śledzone. W sekcjach poniżej znajdziesz opis typów danych obsługiwanych w ExerciseClient.

Typy danych o ćwiczeniach dostępne na wszystkich urządzeniach

Te typy danych o aktywności są dostępne na wszystkich urządzeniach.

  • Przykładowe typy danych mają odpowiedni typ danych _STATS, który zwraca minimalne, maksymalne i średnie wartości z ćwiczenia. Na przykład statystyki PACE można pobrać za pomocą typu danych PACE_STATS.
  • Typy danych interwałów mają odpowiedni typ danych _TOTAL, który zwraca wartość skumulowaną z ćwiczenia. Na przykład statystyki DISTANCE można pobrać za pomocą typu danych DISTANCE_TOTAL.
Tabela 1. Typy danych o ćwiczeniach dostępne na wszystkich urządzeniach
Wskaźnik Oczekiwane dane Uwagi dotyczące oczekiwanych zachowań
HEART_RATE_BPM Uderzenia na minutę [DataType: Double] Podczas ćwiczeń wszystkie urządzenia mierzą tętno raz na sekundę. Niektóre urządzenia zgłaszają wartość BPM co sekundę. Niektóre urządzenia zgłaszają BPM tylko wtedy, gdy zmieni się on od poprzedniej wartości. Nie oczekuj, że na wszystkich urządzeniach będziesz otrzymywać wartość BPM w każdym sekundowym przedziale czasu.
LOKALIZACJA Długość i szerokość geograficzna [DataType: Double] Dane o lokalizacji są oparte tylko na GPS-ie zegarka. Nie oczekuj, że dane o lokalizacji będą pochodzić z usługi Fused Location Provider ani z innych usług Androida. Każdy punkt danych zawiera też wartość dokładności (znaną też jako błąd pozycji poziomej) i dostępność.
KROKI [Typ danych: Long] Liczba kroków to łączna liczba kroków wykonanych podczas ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie było wstrzymane.
DYSTANS Metry [Typ danych: Double] Obliczana na podstawie lokalizacji GPS, gdy jest dostępna, a w innych przypadkach na podstawie liczby kroków. Łączny czas odnosi się do całego czasu trwania ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie jest wstrzymane.
SZYBKOŚĆ [metry / sekundę] [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Zwraca wartości minimalną, maksymalną i średnią. Są one obliczane na podstawie czasu trwania ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie jest wstrzymane.
PACE [sekundy / metr] [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Jeśli prędkość wynosi 0, wartością domyślną jest 0. Średnie wartości są obliczane na podstawie czasu trwania ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie jest wstrzymane.
ELEVATION_GAIN metry, [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Dodatnie zmiany wysokości. Łączna wartość jest podawana w okresie trwania ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie jest wstrzymane.
TOTAL_CALORIES kCal [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Kalorie spalone podczas aktywności dodane do podstawowej przemiany materii. Spalone kalorie uwzględniają wzrost, wagę, wiek i płeć użytkownika określone w ustawieniach systemu. Kalorie nie uwzględniają żadnych danych profilu użytkownika zebranych w aplikacji. Podana łączna liczba kalorii dotyczy czasu trwania ćwiczenia, z wyłączeniem czasu, w którym ćwiczenie jest wstrzymane.

Opcjonalne typy danych o ćwiczeniach

Poniższa lista typów danych jest dostępna tylko na niektórych urządzeniach. Pełną listę DataTypes znajdziesz w dokumentacji Jetpacka. Jeśli symbol DataType nie znajduje się na powyższej liście „wymagane/gwarantowane”, jest opcjonalny.

Oto przykłady opcjonalnych typów danych. Ta lista nie jest wyczerpująca:

Tabela 2. Przykłady opcjonalnych typów danych o ćwiczeniach
Wskaźnik Oczekiwane dane Uwagi dotyczące oczekiwanych zachowań
ABSOLUTE_ELEVATION [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji]
SPADEK_WYSOKOŚCI Metry [Typ danych: Double] Ujemne zmiany wysokości. Wartość jest dodatnia. Na przykład utrata wysokości o 1 m jest zwracana jako 1, a nie –1.
STEPS_PER_MINUTE [Typ danych: Long]
WHEELCHAIR_PUSHES [Typ danych: Long] Liczba pchnięć wózka inwalidzkiego do wykorzystania w ćwiczeniach na wózku.
REP_COUNT [Typ danych: Long]
SWIM_STROKE_COUNT [Typ danych: Long]
SWIM_LAP_COUNT [Typ danych: Long]

Typy danych według ćwiczenia

Dla każdego typu ćwiczeń zwracane są różne typy danych. Zwracane typy danych są zgodne z potrzebami ćwiczenia. Na przykład typ aktywności FIZYCZNA nie zwraca typu danych LICZBA_KROKÓW. Użyj metody Capabilities w czasie działania, aby określić, które typy danych są obsługiwane na urządzeniu użytkownika.

Wszystkie rodzaje ćwiczeń zwracają co najmniej dane o tętnie i spalonych kaloriach. Inne ćwiczenia mogą obsługiwać dodatkowe typy danych w zależności od wymagań dotyczących ćwiczenia.

Oto kilka przykładów:

  • Ćwiczenia takie jak medytacja czy pilates obsługują tylko tętno i kalorie.
  • Ćwiczenia takie jak koszykówka czy badminton obsługują pomiar tętna, kalorii, dystansu i kroków.
  • Ćwiczenia takie jak chodzenie i bieganie obsługują tętno, kalorie, dystans, kroki, prędkość i tempo.
  • Pływanie obsługuje pomiar tętna, spalonych kalorii, dystansu i liczby przepłyniętych długości basenu.

Klient monitorowania pasywnego

Wszystkie urządzenia z Wear OS muszą obsługiwać te typy danych, aby aplikacje mogły pasywnie monitorować dane o zdrowiu i aktywności fizycznej, takie jak tętno
i liczba kroków. Każdy z tych typów danych musi pochodzić wyłącznie z danych generowanych przez czujniki na zegarku.

Oczekiwane zachowania

Aby oszczędzać energię, odczyty czujników uzyskane za pomocą monitorowania pasywnego są przechowywane na mikrokontrolerze i przesyłane do Usług zdrowotnych w pakietach. Wyniki są zwracane w różnych odstępach czasu w zależności od działania systemu. Przykłady to zwracanie partii, gdy bufory czujników są pełne lub gdy użytkownik wchodzi w interakcję z wyświetlaczem.

Nie zakładaj żadnych wstępnie zdefiniowanych ani przewidywalnych interwałów przetwarzania wsadowego w przypadku żadnych typów danych.

Typy danych monitorowania pasywnego

Tabela 3. Wymagane typy danych pasywnego monitorowania na urządzeniach z Wear OS
Wskaźnik Oczekiwane dane Notes
HEART_RATE_BPM Uderzenia na minutę [Typ danych: Double] Urządzenia mogą zwracać odczyty tętna w różnych odstępach czasu. Niektóre urządzenia mogą odczytywać dane co sekundę. Inne urządzenia mogą odczytywać dane co 10 minut. Te interwały nie są udostępniane aplikacjom. Aplikacje powinny się dobrze dostosowywać do różnych interwałów próbkowania.
STEPS_DAILY/STEPS [Typ danych: Long] Dzienny pomiar kroków to łączna liczba kroków zrobionych od ostatniego resetu, który jest wywoływany przez WHS o północy. Obejmuje to kroki wykonane podczas wstrzymania aktywnego ćwiczenia. Kroki to szczegółowa różnica od ostatniego sprawdzenia.
DISTANCE_DAILY/DISTANCE metry [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Obliczone na podstawie akcelerometru/kroków. Nie obliczaj podczas korzystania z GPS, aby użytkownicy, którzy wyłączyli usługi lokalizacyjne, nadal mogli otrzymywać dokładne dane o liczbie kroków.
SZYBKOŚĆ [metry / sekundę] [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji]
CALORIES_DAILY kCal [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Kalorie na dany dzień, w tym kalorie z aktywności i podstawowa przemiana materii. Wartość kalorii podana w tym miejscu uwzględnia wzrost, wagę, wiek i płeć użytkownika określone w ustawieniach systemu. Kalorie nie są dostosowywane na podstawie żadnych danych profilu użytkownika zebranych w Twojej aplikacji.
RUNNING_STEPS (opcjonalnie) [Typ danych: Long] Różnica w liczbie kroków podczas ćwiczeń i w innych sytuacjach. Śledź oba jednocześnie.
WALKING_STEPS (opcjonalnie) [Typ danych: Long]
ELEVATION_GAIN metry [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Obejmuje tylko dodatnie różnice wysokości
SPADEK_WYSOKOŚCI metry [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Obejmuje tylko ujemne różnice wysokości
FLOORS_DAILY [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Może być reprezentowana jako „częściowe” piętra.

Pasywne monitorowanie dziennych celów

Tabela 4. Dane dotyczące dziennych celów w zakresie pasywnego monitorowania
Wskaźnik Oczekiwane dane Notes
STEPS_DAILY [Typ danych: Long] Dzienne kroki, w tym kroki zrobione podczas wstrzymania aktywnego ćwiczenia, to łączna liczba kroków zrobionych od ostatniego resetu. WHS resetuje się o północy.
FLOORS_DAILY [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Może być przedstawiony jako „częściowe” piętra schodów.
CALORIES_DAILY kCal [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Kalorie na dany dzień, w tym kalorie z aktywności i PPM.
DISTANCE_DAILY metry [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Obliczone na podstawie akcelerometru lub liczby kroków. Nie obliczaj tej wartości za pomocą GPS, aby użytkownicy, którzy wyłączyli usługi lokalizacyjne, nadal mogli otrzymywać dokładne dane o liczbie kroków.
DAILY_ELEVATION_GAIN metry [Typ danych: liczba zmiennoprzecinkowa o podwójnej precyzji] Obejmuje tylko dodatnie różnice wysokości

MeasureClient

Użyj MeasureClient, aby zmierzyć tętno w danym momencie.

Oczekiwane zachowania

MeasureClient i PassiveClient są pod pewnymi względami podobne. Obie usługi dostarczają nieprzetworzone statystyki zdrowotne niezwiązane z ćwiczeniami. Oba te parametry służą do pomiaru tętna, ale główna różnica polega na tym, że MeasureClient uwzględnia dostępność danych o tętnie, a PassiveClient nie zawiera informacji o dostępności.

Typy danych

Tabela 5. MeasureClient typy danych
Wskaźnik Oczekiwane dane Notes
HEART_RATE_BPM Uderzenia na minutę [Typ danych: Double] Zawiera też informacje o dostępności

Obsługiwane funkcje

Oprócz typów danych o aktywności fizycznej i typów danych z monitorowania pasywnego urządzenia obsługują dodatkowe funkcje wywoływania zdarzeń, takich jak rozpoczęcie ćwiczeń, oraz pomiaru stanu, np. snu i czuwania. Niektóre z tych funkcji są dostępne na wszystkich urządzeniach, a inne tylko na niektórych.

Aktywatory zdarzeń

Wszystkie urządzenia obsługują te typowe wyzwalacze:

  • dzienne cele dotyczące dystansu i kroków,
  • Cele ćwiczeń dotyczące kroków, dystansu i czasu trwania.

Inne urządzenia mogą obsługiwać bardziej zaawansowane wyzwalacze zdarzeń. Przykłady:

  • Liczenie okrążeń podczas pływania
  • Cele ćwiczeń dotyczące spalonych kalorii
  • Cele ćwiczeń dotyczące prędkości chwilowej

Stany

Wszystkie urządzenia obsługują podstawowe funkcje stanu. Funkcja stanu określa, czy użytkownik wykonuje aktywne ćwiczenie.

Inne urządzenia mogą oferować dodatkowe funkcje stanu. Dodatkowe funkcje stanu obejmują wykrywanie, czy ćwiczenie zostało automatycznie wstrzymane lub wznowione, a także czy użytkownik śpi, czy nie.

Alerty dotyczące stanu w monitorowaniu pasywnym

Niektóre urządzenia obsługują alerty dotyczące zdrowia. Te funkcje nie są obsługiwane na wszystkich urządzeniach. Niektóre alerty zdrowotne obejmują wykrywanie nieprawidłowości tętna lub upadków.