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

Interfejs Wear Health Services API (WHS) jest obowiązkowym komponentem na wszystkich urządzeniach z Wear OS 3 lub nowszym, ponieważ zapewnia spójną platformę integracji dla deweloperów treści o zdrowiu i fitnessu. Zaprojektuj aplikację tak, by płynnie dostosowywać się do wielu urządzeń i ich różnych możliwości. Pozwoli to na zachowanie zgodności na różnych urządzeniach i uniknięcie problemów z wygodą użytkowników. Aby to zrobić, zadeklaruj zależności tylko w przypadku klientów, których używa Twoja aplikacja. Zapewnij też aplikacji możliwość wyświetlania lub usuwania opcjonalnych danych zaawansowanych w zależności od ich dostępności.

Różne czujniki generują dane z różnymi częstotliwościami, które różnią się w zależności od używanego urządzenia i platformy czujników. Urządzenie może na przykład zwracać tętno w różnych sygnaturach czasowych, a inne – w innej lokalizacji. Twórz aplikacje, które mogą otrzymywać niezależne strumienie danych w różnych sygnaturach czasowych lub w pokrywających się sygnaturach czasowych.

W tym przewodniku opisujemy oczekiwane zachowania i typy danych obsługiwane przez różne klienty w usługach Wear Health.

Klient ćwiczenia

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

Oczekiwane zachowania

W przypadku ExerciseClient niektóre rodzaje ć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 pchane są pchnięcia wózka inwalidzkiego. Włącz lub wyłącz te opcje w zależności od ich dostępności na danym urządzeniu.

Większość typów danych dotyczących ćwiczeń jest próbkowana i dostarczana w 1-sekundowych odstępach, z pewnymi wyjątkami:

  • Czasami niektóre typy danych ćwiczeń 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.

Dostarczanie danych może odbywać się strumieniowo lub wsadowo. Dane są przesyłane strumieniowo, gdy procesor aplikacji jest włączony, czyli zwykle wtedy, gdy wyświetlacz jest włączony i interaktywny. Po wyłączeniu lub przejściu w tryb nieaktywny (włączony, ale nieinteraktywne) dane są grupowane w celu oszczędzania energii. Dane wsadowe są dostarczane do aplikacji, gdy procesor aplikacji włączy się ponownie, ponieważ zegarek wyszedł z trybu nieaktywnego, lub gdy bufory do grupowania są zapełnione (co zależy od urządzenia). Gdy urządzenie działa w trybie nieaktywnym, częstotliwość próbkowania pozostaje taka sama, więc dostarczana wsada nadal ma punkty danych o dużej częstotliwości.

Typy danych są określane wyłącznie na podstawie danych wygenerowanych przez czujniki zegarka. Na przykład dane o lokalizacji pochodzą wyłącznie z zegarka, a nie z telefonu.

Typy danych

Interfejs ExerciseClient API pozwala uruchamiać, wstrzymywać, wznawiać i zatrzymywać treningi różnych typów. Dla każdego ćwiczenia WHS definiuje zestaw typów danych, które są dostępne dla każdego ćwiczenia. Oszczędza to energię i upraszcza logikę aplikacji, ponieważ czujniki, które nie są wymagane dla danego ćwiczenia, nie są włączone. Na przykład, gdy rozpoczynasz bieg, dane o lokalizacji są dostarczane i śledzone tylko w przypadku biegu na zewnątrz. Po rozpoczęciu ćwiczenia rowerowego kroki nie są podawane ani śledzone. W kolejnych sekcjach znajdziesz opisy typów danych obsługiwanych w usłudze ExerciseClient.

Typy gwarantowanych danych dotyczących ćwiczeń

Poniższe typy danych ćwiczeń są dostępne na wszystkich urządzeniach.

  • Przykładowe typy danych mają odpowiedni typ danych _STATS, który zwraca wartości minimalną, maksymalną i średnią z ćwiczenia. Na przykład statystyki PACE można pobierać za pomocą typu danych PACE_STATS.
  • Typy danych z przedziałami mają odpowiedni typ danych _TOTAL, który zwraca łączną wartość z ćwiczenia. Na przykład statystyki DISTANCE można pobierać z typem danych DISTANCE_TOTAL.
Dane Oczekiwane dane Uwagi na temat oczekiwanego działania
HEART_RATE_BPM Uderzenia na minutę [DataType: Double] Wszystkie urządzenia sprawdzają tętno raz na sekundę podczas ćwiczeń. Niektóre urządzenia zgłaszają wartość BPM co sekundę. Niektóre urządzenia raportują BPM tylko wtedy, gdy wartość ta zmieniła się od poprzedniej wartości. Nie spodziewaj się wartości uderzeń na minutę w każdym 1-sekundowym przedziale czasu na żadnym urządzeniu.
LOKALIZACJA Długość i szerokość geograficzna [DataType: Double] Dane o lokalizacji opierają się wyłącznie na GPS-ie zegarka. Dane o lokalizacji nie będą pochodzić od dostawcy uśrednionej lokalizacji ani od innych usług na Androida. Każdy punkt danych zawiera też wartość dokładności (zwaną też błędem pozycji w poziomie) i dostępność.
KROKI [Typ danych: długi] Liczba kroków jest sumą biegów trwającą czas trwania ćwiczenia, nie wliczając czasu wstrzymania ćwiczenia
DYSTANS Metry [typ danych: liczba zmiennoprzecinkowa] Obliczone na podstawie lokalizacji GPS, jeśli jest to możliwe, lub na podstawie kroków w innym przypadku. Suma oznacza całkowitą ilość czasu trwania ćwiczenia, bez uwzględnienia czasu, gdy ćwiczenie zostało wstrzymane.
SZYBKOŚĆ [metry / s] [Typ danych: liczba zmiennoprzecinkowa] Zwraca wartości minimalne, maksymalne i średnie. Są one związane z czasem trwania ćwiczenia, bez uwzględnienia czasu jego wstrzymania.
TEMPO [sekundy / metr] [Typ danych: liczba zmiennoprzecinkowa] Jeśli prędkość wynosi 0, wartość domyślna to 0. Średnie wartości dotyczą czasu trwania ćwiczenia i nie obejmują czasu, w którym ćwiczenie zostało wstrzymane.
ELEVATION_GAIN Metry [Typ danych: liczba zmiennoprzecinkowa] Dodatnie zmiany wysokości. Podawane są sumy obejmujące cały czas trwania ćwiczenia, nie wliczając czasu, w którym zostało ono wstrzymane.
TOTAL_KALORIES kCal [typ danych: liczba zmiennoprzecinkowa] Kalorie spalone podczas aktywności dodane do podstawowej przemiany materii. Emisyjne kalorie uwzględniają wzrost, wagę, wiek i płeć użytkownika, określone w ustawieniach systemu. Kalorie nie uwzględniają żadnych danych z profilu użytkownika zebranych w Twojej aplikacji. Łączna liczba raportowana obejmuje czas trwania ćwiczenia i nie obejmuje czasu jego wstrzymania.

Opcjonalne typy danych ćwiczeń

Poniższa lista typów danych jest dostępna tylko na niektórych urządzeniach. Pełną listę typów danych znajdziesz w dokumentacji Jetpacka. Jeśli elementu DataType nie ma na poprzedniej liście „wymagane/gwarantowane”, jest to opcjonalne.

Poniżej znajdziesz przykłady opcjonalnych typów danych. Ta lista nie jest wyczerpująca:

Dane Oczekiwane dane Uwagi na temat oczekiwanego działania
ABSOLUTE_ELEVATION [Typ danych: liczba zmiennoprzecinkowa]
ELEVATION_LOSS Metry [typ danych: liczba zmiennoprzecinkowa] Ujemne zmiany wysokości. Wartość jest dodatnia. Na przykład spadek wysokości o 1 m jest zwracany jako 1, a nie -1.
STEPS_PER_MINUTE [Typ danych: długi]
WHEELCHAIR_PUSHES [Typ danych: długi] Liczba pchnięć kół wózka inwalidzkiego do wykorzystania w ćwiczeniach na wózku.
REP_COUNT [Typ danych: długi]
SWIM_STROKE_COUNT [Typ danych: długi]
PŁYWANIE_LAP_COUNT [Typ danych: długi]

Typy danych na ćwiczenie

Dla każdego rodzaju ćwiczenia zwracane są różne typy danych. Zwracane typy danych są zgodne z potrzebami danego ćwiczenia. Na przykład typ Ćwiczenie BIKING nie zwraca typu danych KROKI. Aby określić, jakie typy danych są obsługiwane na urządzeniu użytkownika, używaj metody Capabilities w czasie działania.

Jako minimum wszystkie rodzaje ćwiczeń zwracają dane dotyczące tętna i kalorii. Inne ćwiczenia mogą obsługiwać dodatkowe typy danych w zależności od wymagań konkretnego ćwiczenia.

Oto kilka przykładów:

  • Ćwiczenia takie jak medytacja czy pilates pomagają tylko w zwiększaniu tętna i kalorii
  • Ćwiczenia takie jak koszykówka czy badminton podnoszą tętno, kalorie, dystans i kroki.
  • Ćwiczenia takie jak chodzenie czy bieganie wspomagają tętno, kalorie, dystans, kroki, prędkość i tempo.
  • Pływanie wspomaga tętno, kalorie, dystans i okrążenia

Klient monitorowania pasywnego

Poniższe typy danych są wymagane na wszystkich urządzeniach z Wear OS na potrzeby obsługi aplikacji, które pasywnie monitorują dane o zdrowiu, takie jak tętno czy liczba kroków. Każdy z tych typów danych musi pochodzić wyłącznie z danych wygenerowanych przez czujniki zegarka.

Oczekiwane zachowania

W celu oszczędzania energii odczyty z czujników uzyskane za pomocą monitoringu pasywnego są przechowywane w MCU i grupowane w ramach opieki zdrowotnej. Te zbiorcze wyniki są zwracane w różnych odstępach czasu w zależności od działania systemu. Mogą to być na przykład zwracane wsady, gdy bufory czujników są zapełnione lub gdy użytkownik wchodzi w interakcję z wyświetlaczem.

Nie zakładaj żadnych zdefiniowanych wstępnie ani przewidywalnych odstępów czasu wsadowego dla żadnych typów danych.

Typy danych monitorowania pasywnego

Dane Oczekiwane dane Notes
HEART_RATE_BPM Uderzenia na minutę [Data type: Double] Urządzenia mogą zwracać odczyty tętna w różnych odstępach czasu. Niektóre urządzenia mogą wymagać odczytu co sekundę. Inne urządzenia mogą wykonywać odczyt co 10 minut. Przedziały te nie są dostępne dla aplikacji. Aplikacje powinny płynnie dostosowywać się do różnych przedziałów częstotliwości próbkowania.
KROKI_DZIEŃ/KROKI [Typ danych: długi] Dzienne kroki to całkowita liczba kroków zrobionych od ostatniego resetowania, które zostało aktywowane przez WHS o północy. Obejmuje to kroki wykonane, gdy aktywne ćwiczenie jest wstrzymane. Liczba kroków to szczegółowa różnica od ostatniego sprawdzenia.
DISTANCE_DAILY/DISTANCE metry [typ danych: liczba zmiennoprzecinkowa] Obliczone na podstawie akcelerometru/kroków. Nie obliczaj w trakcie korzystania z GPS-a, aby użytkownicy, którzy wyłączyli usługi lokalizacyjne, nadal mogli otrzymywać dokładne liczby kroków.
SZYBKOŚĆ [metry / s] [Typ danych: liczba zmiennoprzecinkowa]
CALORIES_DAILY kCal [typ danych: liczba zmiennoprzecinkowa] Kalorie na dany dzień, w tym kalorie podczas aktywności i BMR. Wyświetlana tutaj wartość kalorii uwzględnia wzrost, wagę, wiek i płeć użytkownika, określone w ustawieniach systemu. Kalorie nie są dostosowywane na podstawie danych z profilu użytkownika zebranych przez Twoją aplikację.
RUNNING_STEPS (opcjonalnie) [Typ danych: długi] Różnica kroków zarówno w trakcie ćwiczenia, jak i w innych sytuacjach. Śledź oba jednocześnie.
WALKING_STEPS (opcjonalnie) [Typ danych: długi]
ELEVATION_GAIN metry [typ danych: liczba zmiennoprzecinkowa] Uwzględnia tylko dodatnie delty wysokości
ELEVATION_LOSS metry [typ danych: liczba zmiennoprzecinkowa] Uwzględnia tylko ujemne delty wysokości
FLOORS_DAILY [Typ danych: liczba zmiennoprzecinkowa] Może być przedstawiona jako „częściowe” piętra.

Bierne monitorowanie dziennych celów

Dane Oczekiwane dane Notes
KROKI_DZIENNIE [Typ danych: długi] Dzienne kroki, w tym kroki zrobione, gdy aktywne ćwiczenie jest wstrzymane, to łączna liczba kroków zrobionych od ostatniego resetu. WHS jest resetowane o północy.
FLOORS_DAILY [Typ danych: liczba zmiennoprzecinkowa] Może być zaprezentowane jako „częściowe” piętra schodów.
CALORIES_DAILY kCal [typ danych: liczba zmiennoprzecinkowa] Kalorie na dany dzień, w tym aktywne kalorie i BMR.
DISTANCE_DAILY metry [typ danych: liczba zmiennoprzecinkowa] Obliczane na podstawie akcelerometru lub liczby kroków. Nie obliczaj tego za pomocą GPS, aby użytkownicy, którzy wyłączyli usługi lokalizacyjne, nadal mogli otrzymywać dokładne liczby kroków.
DAILY_ELEVATION_GAIN: metry [typ danych: liczba zmiennoprzecinkowa] Uwzględnia tylko dodatnie delty wysokości

MeasureClient

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

Oczekiwane zachowania

MeasureClient i PassiveClient są podobne pod pewnymi względami. Obie dostarczają statystyki dotyczące zdrowia, które nie są związane z ćwiczeniami. Możesz używać obu tych funkcji do pomiaru tętna, ale główna różnica polega na tym, że MeasureClient uwzględnia dostępność danych o tętnie, ale PassiveClient nie podaje informacji o dostępności.

Typy danych

Dane Oczekiwane dane Notes
HEART_RATE_BPM Uderzenia na minutę [Data type: Double] Obejmuje też dostępność

Obsługiwane funkcje

Oprócz typów danych dotyczących ćwiczeń i pasywnych danych monitorowania urządzenia obsługują dodatkowe funkcje wyzwalające zdarzenia, takie jak rozpoczęcie ćwiczenia i pomiar stanu snu lub przebudzenia. Część z nich jest dostępna na wszystkich urządzeniach, a inne tylko na wybranych.

Aktywatory zdarzeń

Wszystkie urządzenia obsługują te typowe reguły:

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

Inne urządzenia mogą obsługiwać bardziej zaawansowane aktywatory zdarzeń. Oto kilka przykładów:

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

Stany

Wszystkie urządzenia obsługują podstawowe funkcje stanu. Funkcjonalność stanowa odnosi się do tego, czy użytkownik wykonuje obecnie ćwiczenie

Inne urządzenia mogą udostępniać dodatkowe funkcje dotyczące stanu. Niektóre dodatkowe funkcje stanu obejmują wykrywanie, czy ćwiczenie zostało automatycznie wstrzymane lub wznowione, a także czy użytkownik jest przebudzony lub uśpiony.

Alerty zdrowotne przy pasywnym monitorowaniu

Niektóre urządzenia obsługują alerty dotyczące stanu zdrowia. Te funkcje nie są obsługiwane na wszystkich urządzeniach. Niektóre alerty zdrowotne obejmują wykrywanie zaburzeń tętna lub upadki.