Tworzenie funkcji związanych z krokami za pomocą interfejsu Google Health API

Interfejs Google Health API śledzi kroki użytkownika i dane o aktywności za pomocą stepstypu danych interwału. Liczba kroków to podstawowy wskaźnik codziennej aktywności fizycznej, który pomaga deweloperom śledzić postępy w zakresie kondycji, obliczać wydatkowaną energię i tworzyć podsumowania codziennej aktywności dla użytkowników.

Dowiedz się, jak odczytywać i strukturyzować dane dotyczące liczby kroków w aplikacji, aby zapewnić użytkownikom jak najlepsze wrażenia.

Obsługiwane typy danych

Interfejs API obsługuje ten typ danych do śledzenia liczby kroków:

Tabela. Typy danych kroków w interfejsie Google Health API

Typ danych	Dostępne operacje	Zakres
Instrukcje dataType: steps filter parameter: steps Typ rekordu: Interwał Rozdzielczość przechowywania: 1 minuta Obsługa webhooków Obsługa wartości zerowych Przewodnik z instrukcjami Zgodne urządzenia Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

Wytyczne

Podczas integrowania śledzenia kroków w aplikacji postępuj zgodnie z tymi wytycznymi dotyczącymi projektowania i wdrażania.

Obliczanie szybkości i tempa

Interfejs Google Health API używa standardowych wzorów do obliczania prędkości i tempa:

• Prędkość = distance / time(hour)
• Tempo = time(seconds) / distance

Jednostkę odległości określa nagłówek Accept-Language podany w żądaniu.

Codzienne podsumowanie

Aby prawidłowo agregować dzienne liczby kroków podczas podróży, zmian stref czasowych lub czasu letniego, nie wykonuj obliczeń czasu trwania po stronie klienta. Zamiast tego wysyłaj zapytania do punktu końcowego dailyRollUp, który automatycznie uzupełnia luki w danych fizycznych za pomocą przesunięć UTC. Podsumowanie zwraca obiekt StepsRollupValue zawierający pole countSum, które reprezentuje łączną liczbę kroków zrobionych w danym dniu.

Rysowanie interfejsów użytkownika (uzgadnianie)

Podczas tworzenia elementów interfejsu do wyświetlania danych o krokach używaj punktu końcowego reconcile. Jeśli kilka źródeł danych (np. smartwatch i telefon komórkowy) zarejestrowało kroki w tym samym czasie, punkt końcowy reconcile rozwiązuje konflikty i scala strumienie, aby zwrócić jeden uzgodniony strumień danych.

Informacje o obsłudze nakładających się przedziałów czasu z synchronizacji połączonych urządzeń i o możliwości zmiany sygnatur czasowych znajdziesz w przewodniku po zarządzaniu danymi.

Śledzenie w ciągu dnia i histogramy

Aby wyświetlić szczegółową aktywność użytkowników w ciągu dnia (np. wykresy):

• Histogramy z krokami godzinowymi lub minutowymi: wyślij zapytanie do punktu końcowego rollUp, określając czas trwania (np. 60s dla 1 minuty lub 3600s dla 1 godziny) za pomocą parametru windowSize. Dane o krokach są rejestrowane w 1-minutowych (60s) odstępach czasu, więc ustaw wartość windowSize na co najmniej 60s. Żądania z okresem krótszym niż minuta (np. 10s lub 30s) nie dzielą poszczególnych sum minutowych, ale umieszczają pełną liczbę z minuty w pierwszym pasującym podzakresie. Więcej informacji znajdziesz w artykule Rozmiar okna zbiorczego i rozdzielczość pamięci bazowej.
• Wszystkie rekordy kroków: użyj punktu końcowego list, aby pobrać najbardziej szczegółowe, surowe rekordy kroków.

Punkty końcowe rollUp, dailyRollUp i reconcile akceptują parametr dataSourceFamily, który umożliwia filtrowanie danych z określonych grup źródeł. Więcej informacji i przykłady użycia znajdziesz w sekcji Filtrowanie według rodziny źródeł danych w przewodniku Filtrowanie danych.

Synchronizacja w czasie rzeczywistym za pomocą webhooków

Subskrybuj kolekcję typu danych steps, aby otrzymywać powiadomienia w czasie rzeczywistym, gdy zostaną zaimportowane lub zsynchronizowane nowe dane dotyczące kroków. Zamiast odpytywać punkty końcowe REST, aktualizuj dynamicznie panele po stronie klienta w odpowiedzi na te powiadomienia webhook. Szczegółowe informacje o konfigurowaniu subskrypcji znajdziesz w artykule Subskrypcje webhooków.

Obsługa prawdziwych zer

Interfejs Google Health API wykorzystuje prawdziwe zera do rozwiązywania problemów z okresami bezruchu. Jeśli użytkownik nosi tracker, ale w danym okresie nie chodzi, interfejs API zwraca rekord dla tego przedziału czasu, który zawiera normalne źródło danych i metadane sygnatury czasowej, ale pomija właściwość count.

Dzięki temu możesz odróżnić:

• Okresy, w których urządzenie jest noszone na nadgarstku, ale użytkownik nie chodzi: użytkownik nosi urządzenie, ale nie chodzi. Spowoduje to zwrócenie rekordów bez właściwości count (interpretowanej jako 0 kroków).
• Okresy, w których urządzenie nie jest noszone na nadgarstku: użytkownik nie nosi urządzenia. Nie zwraca to żadnego rekordu, co powoduje duże luki w danych.

Więcej informacji znajdziesz w przewodniku Obecność danych i prawdziwe zera.