Aby aplikacja dobrze współpracowała z Health Connect, zalecamy stosowanie się do tych wytycznych dotyczących sprawdzonych metod.
Zapisywanie danych
Aplikacje mogą zapisywać w Health Connect wyłącznie dane pochodzące z własnych źródeł.
Jeśli dane w Twojej aplikacji zostały zaimportowane z innej aplikacji, ponosi ona odpowiedzialność za zapisanie własnych danych w Health Connect.
Warto też wdrożyć logikę obsługującą wyjątki zapisu, takie jak dane spoza granic lub wewnętrzny błąd systemu. Możesz zastosować strategie wycofywania i ponowienia w mechanizmie planowania zadań. Jeśli zapisywanie w Health Connect nie powiedzie się, sprawdź, czy aplikacja może zostać przeniesiona poza ten punkt eksportu. Nie zapomnij zapisać i zgłosić błędów, aby wspomóc diagnozę.
Podczas śledzenia danych możesz skorzystać z 2 sugestii, z których możesz skorzystać w zależności od sposobu, w jaki aplikacja zapisuje dane.
Śledzenie pasywne
Dotyczy to aplikacji, które pasywnie monitorują stan zdrowia lub aktywność fizyczną, np. rejestrują kroki lub tętno w tle.
Twoja aplikacja musi okresowo zapisywać dane w Health Connect w taki sposób:
- Przy każdej synchronizacji zapisuj tylko nowe dane i aktualizuj te, które zostały zmodyfikowane od ostatniej synchronizacji.
- Żądania fragmentów do maksymalnie 1000 rekordów na jedno żądanie zapisu.
- Użyj
WorkManager
, aby zaplanować okresowe zadania w tle przez co najmniej 15 minut. Ogranicz zadania do wykonywania tylko wtedy, gdy urządzenie jest bezczynne i nie ma niskiego poziomu baterii.
val constraints = Constraints.Builder() .requiresBatteryNotLow() .requiresDeviceIdle(true) .build() val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>( 15, TimeUnit.MINUTES, 5, TimeUnit.MINUTES ) .setConstraints(constraints) .build()
Aktywne śledzenie
Dotyczy to aplikacji, które śledzą zdarzenia na podstawie zdarzeń, np. ćwiczenia i sen, lub ręcznie podają dane na temat odżywiania. Rekordy są tworzone, gdy aplikacja działa na pierwszym planie, lub w rzadkich przypadkach, gdy jest używana kilka razy dziennie.
Dopilnuj, aby aplikacja Health Connect nie działała przez cały czas trwania zdarzenia.
Dane należy zapisać w Health Connect na 1 z 2 sposobów:
- Po zakończeniu wydarzenia zsynchronizuj dane z Health Connect. Na przykład synchronizować dane, gdy użytkownik zakończy śledzoną sesję ćwiczeniową.
- Zaplanuj jednorazowe zadanie za pomocą
WorkManager
, aby zsynchronizować dane później.
Współczynnik próbkowania
Podczas zapisywania danych w Health Connect używaj odpowiednich częstotliwości próbkowania, aby zmniejszyć obciążenie pamięci masowej. Warto np. zastanowić się, jak często muszą być rejestrowane dane o liczbie kroków oraz jakie typy danych o częstotliwości próbkowania powiązane z aktywnym treningiem (np. prędkość) są wymagane.
Nie każdy typ danych wymaga takiej samej częstotliwości próbkowania. Aktualizowanie danych o liczbie kroków co sekundę nie daje żadnych korzyści w przeciwieństwie do mniejszej częstotliwości, np. co 60 sekund. Wyższe częstotliwości próbkowania mogą jednak zapewnić użytkownikom bardziej szczegółowe i szczegółowe dane na temat ich zdrowia i aktywności fizycznej. Częstotliwość próbkowania musi zachować równowagę między szczegółowością a wydajnością.
Synchronizuj dane
Na proces synchronizacji mają wpływ następujące czynniki.
Wygaśnięcie tokena
Nieużywany token Changes wygasa w ciągu 30 dni, dlatego musisz użyć strategii synchronizacji, która w takim przypadku pozwoli uniknąć utraty informacji. Strategia może obejmować takie podejścia:
- Wyszukaj w magazynie danych aplikacji ostatnio skonsumowany rekord, który zawiera również
id
z Health Connect. - Wysyłaj do Health Connect prośby o rejestry zaczynające się od określonej sygnatury czasowej, a następnie wstawiaj je lub aktualizuj w magazynie danych aplikacji.
- Poproś o token zmian, aby zarezerwować go na przyszłość.
Zalecane strategie zarządzania zmianami
Jeśli Twoja aplikacja otrzymuje nieprawidłowe lub wygasłe tokeny zmian, w zależności od zastosowania tych tokenów w Twojej logice zalecamy stosowanie tych strategii zarządzania:
- Odczytywanie i usuwanie duplikatów danych. To najlepsza strategia.
- Przechowuj sygnaturę czasową ostatniego odczytu danych z Health Connect.
- Po wygaśnięciu tokena ponownie odczytaj wszystkie dane z ostatniej sygnatury czasowej lub z ostatnich 30 dni. Następnie usuń jego duplikaty z odczytanymi wcześniej danymi za pomocą identyfikatorów.
- Najlepiej zaimplementować identyfikatory Client-ID, ponieważ są one wymagane do aktualizacji danych.
- Odczytuj tylko dane od ostatniej sygnatury czasowej odczytu. Z tego powodu w okresie ważności tokena zmiany mogą występować pewne rozbieżności danych, ale ten czas jest krótszy i może wynosić od kilku godzin do kilku dni.
- Przechowuj sygnaturę czasową ostatniego odczytu danych z Health Connect.
- Po wygaśnięciu tokena odczytuj wszystkie dane od tej sygnatury czasowej.
- Usuń, a następnie odczytaj dane z ostatnich 30 dni. Jest to bardziej zbliżone do tego,
co dzieje się przy pierwszej integracji.
- Usuń z Health Connect wszystkie dane odczytane przez aplikację z ostatnich 30 dni.
- Po usunięciu przeczytaj wszystkie te dane ponownie.
- Odczyt danych z ostatnich 30 dni bez usuwania duplikatów. Jest to najmniej idealna strategia, która powoduje wyświetlanie użytkownikom zduplikowanych danych.
- Usuń z Health Connect wszystkie dane odczytane przez aplikację z ostatnich 30 dni.
- Zezwalaj na zduplikowane wpisy.
Tokeny zmian typu danych
Jeśli Twoja aplikacja niezależnie zużywa więcej niż 1 typ danych, użyj osobnego tokena zmiany do każdego z nich. List wielu typów danych w interfejsie Changes Sync API używaj tylko wtedy, gdy są one używane razem lub nie.
Czytaj na pierwszym planie
Aplikacje mogą odczytywać dane z Health Connect tylko wtedy, gdy działają na pierwszym planie. Podczas synchronizowania danych z Health Connect dostęp do Health Connect może zostać przerwany w dowolnym momencie. Aplikacja musi na przykład radzić sobie z przerwami w trakcie synchronizacji podczas odczytywania dużej ilości danych z Health Connect i kontynuować przy następnym uruchomieniu aplikacji.
Importuj kody czasowe
Aplikacja nie może otrzymywać powiadomień o nowych danych, dlatego sprawdź ich dostępność w 2 miejscach:
- Za każdym razem, gdy aplikacja stanie się aktywna na pierwszym planie. W takim przypadku użyj zdarzeń cyklu życia.
- Okresowo, gdy aplikacja pozostaje na pierwszym planie. Powiadamia użytkowników o nowych danych, aby mogli odpowiednio zaktualizować swoje ekrany.
Ograniczenia liczby żądań
W rzadkich przypadkach Health Connect nakłada ograniczenia liczby żądań z Twojej aplikacji. Ma to na celu ograniczenie wpływu baterii i wydajności urządzenia.
- Zdecydowanie zalecamy stosowanie się do sprawdzonych metod, aby uniknąć odrzucenia żądań aplikacji z powodu ograniczenia liczby żądań.
- Aplikacje powinny być odporne na ograniczanie liczby żądań. Na przykład dane w tle mogą być zapisywane podczas następnego zadania okresowego na wypadek niepowodzenia żądań z powodu ograniczenia liczby żądań.
Wprowadzanie aplikacji
Wiele aplikacji ma niestandardowy proces wdrażania, np. edukację w zakresie funkcji lub prośbę o zgodę użytkownika. Zdecydowanie zalecamy deweloperom eksportowanie aktywności wprowadzającej, którą Health Connect uruchamia, gdy użytkownik po raz pierwszy korzysta z aplikacji. Aby to zrobić, dodaj do pliku manifestu te dane:
<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
android:name=".OnboardingActivity"
android:exported="true"
android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
<intent-filter>
<action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
</intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
android:name="UAndAboveOnboardingActivity"
android:exported="true"
android:targetActivity=".OnboardingActivity"
android:permission="android.permission.health.START_ONBOARDING">
<intent-filter>
<action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
</intent-filter>
</activity-alias>
Pamiętaj, że ta funkcja nie jest jeszcze dostępna na Androidzie 14, ale wkrótce się to zmieni.
Gdy użytkownik spróbuje połączyć Twoją aplikację z Health Connect, wyeksportowana aktywność zostanie uruchomiona. To działanie musi:
- Zawierać wszelkie istotne informacje edukacyjne dla użytkowników, np. wyjaśniające, jakie dane są zapisywane lub odczytywane.
- W razie potrzeby poproś użytkownika o udzielenie zgody.
- Wyślij prośbę o uprawnienia do Health Connect.
- obsługiwać dowolne inne funkcje logiczne specyficzne dla danej aplikacji, takie jak planowanie okresowych pracowników roboczych;
- Gdy to zrobisz, zezwól użytkownikowi na zamknięcie aktywności.
W przypadku aplikacji, które nie eksportują aktywności wprowadzającej, Health Connect wyświetla użytkownikowi ekran Zarządzaj uprawnieniami, gdy próbuje on połączyć aplikację. Może to być akceptowalne w przypadku aplikacji, w których przyznanie uprawnień jest jedynym warunkiem wstępnym do działania integracji.
Pamiętaj, że aktywność wprowadzająca może być uruchomiona więcej niż raz, na przykład jeśli użytkownik później anuluje uprawnienia do aplikacji, a następnie połączy ją ponownie.