Planuj pod kątem skuteczności

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.