Migracja Health Connect z Androida 13 (APK) na Androida 14 (platforma)

Health Connect będzie dołączony do Androida 14 jako wspólna warstwa przechowywania danych o zdrowiu konsumentów, chroniona przez szczegółowe uprawnienia i dostępna jako aplikacja systemowa Androida (w tym dokumencie nazywana „modułem” frameworku).

Deweloperzy powinni traktować plik APK Health Connect (Android 13) jako warstwę zgodności wstecznej dla modelu platformy. Model framework będzie w 100% zgodny z poprzednim plikiem APK.

Podczas przejścia z Androida 13 na 14 niezwykle ważne jest, aby korzystanie z aplikacji było jak najbardziej płynne i intuicyjne.

Ten dokument zawiera plan migracji, przykładowe scenariusze migracji oraz listę zmian w pakiecie Jetpack SDK, które ułatwiają dostęp do interfejsu Health Connect API.

Plan migracji

  1. Po wydaniu Androida 14 Google przejdzie na udostępnianie Health Connect jako aplikacji systemowej Androida.
  2. Gdy osiągniesz zgodność funkcji, dane zostaną uzupełnione z pliku APK.
  3. Wszystkie punkty wejścia będą kierować na interfejs aplikacji systemowej.
  4. Rozpocznie się migracja danych. Podczas migracji interfejsy API modułów będą zawieszone i będą miały stan „Migracja w toku”. Będzie ona też widoczna w interfejsie Health Connect.
  5. Po zakończeniu migracji można odinstalować plik APK.

Przykładowe scenariusze migracji

Oto kilka przykładowych scenariuszy, które opisują proces migracji w przypadku typów danych intervalseries:

Przykład 1. Bieganie (dane interwałowe)

Użytkownik zebrał 10 lat danych z ciągłego pomiaru przez 1 godzinę dziennie. Oznacza to:

  • Exercise Session Records: 365 * 10 * 1
  • Kroki: 365 * 10 * 1
  • Kalorie: 365 * 10 * 1
  • Razem = 365 * 10 * 3 (365 * 30) = 10 150

Ponieważ 1 element odpowiada 3000 rekordom, powyższe dane dają w sumie około 4 elementów.

Nasze wewnętrzne testy potwierdziły, że wstawienie typowego fragmentu zajmuje około sekundy, więc powyższe dane zostałyby przeniesione w ciągu około 4 sekund.

Przykład 2. Tętno (dane seryjne)

Użytkownik zebrał dane o tętnieniu przez 5 lat (z rekordem tworzonym co minutę), co daje łącznie 2 628 000 rekordów.

Przy 3000 rekordów na fragment dane są rozprowadzane na 876 fragmentów. Wstawianie 1 kawałka zajmuje około sekundy, więc migracja danych potrwa mniej niż 15 minut.

Proponowany proces migracji

Zdecydowaliśmy się na natychmiastową migrację. W praktyce oznacza to, że plik APK stanie się nieaktywny, gdy tylko urządzenie zostanie zaktualizowane do Androida 14, przy minimalnej interwencji użytkownika.

Oto ogólny opis procesu migracji:

  1. Użytkownik aktualizuje urządzenie do Androida 14.
  2. Jetpack 14 przekierowuje użytkownika do interfejsów API modułów i blokuje go na czas migracji.
  3. Proces migracji rozpoczyna się, gdy wersja modułu jest zgodna pod względem funkcji z pakietem APK (czyli zawiera ten sam zestaw funkcji lub więcej). Po rozpoczęciu procesu migracji APK przenosi uprawnienia i dane.
    1. Jeśli obie wersje nie są zgodne pod względem funkcji, należy uaktualnić wersję modułu. Po zakończeniu uaktualniania rozpocznie się proces migracji.
  4. Po zakończeniu migracji stan zmieni się na „Migracja zakończona”, a interfejsy API modułów zostaną odblokowane.
  5. Plik APK można teraz odinstalować.

Elementy interfejsu migracji

Przed migracją i w jej trakcie moduł frameworku wyświetla te ekrany w celu edukacji użytkowników:

Rysunek 1. Jeśli plik APK Health Connect nie obsługuje migracji, wyświetli się prośba o jego aktualizację. Jeśli użytkownik odrzuci aktualizację, moduł będzie nadal działać i zacznie gromadzić uprawnienia i dane:

Wymagana aktualizacja telefonu


Rysunek 2. Jeśli moduł frameworku wymaga aktualizacji, aby był zgodny z funkcjami, wyświetli się komunikat z prośbą o przeprowadzenie aktualizacji i ponowne uruchomienie urządzenia. Jeśli użytkownik odrzuci aktualizację, moduł nadal będzie działać i zacznie gromadzić uprawnienia i dane:

Wymagana aktualizacja pliku APK


Rysunek 3. Podczas migracji wyświetla się wskaźnik postępu z tekstem wyjaśniającym, że dane są synchronizowane:

Synchronizacja danych

Dane po usunięciu duplikatów

Jeśli moduł framework zaczął pobierać dane i uprawnienia przed migracją lub przywróceniem z chmury, obowiązują te zasady:

Uprawnienia

Jeśli w module framework są uprawnienia, podczas migracji są ignorowane wszystkie zduplikowane uprawnienia uzyskane z pliku APK.

Dane

Podczas migracji zduplikowane dane pochodzące z pliku APK są ignorowane. Preferowane są nowsze dane z modułu.

Dane są deduplikowane na podstawie wartości clientRecordId, jeśli identyfikator rekordu został podany przez klienta. Jeśli tak nie jest, przedziały czasowe (startTimeendTime w przypadku rekordów wewnętrznych oraz time w przypadku rekordów natychmiastowych) są traktowane jako klucz, podobnie jak typ danych i nazwa pakietu aplikacji.

Zmiany w Jetpack SDK

Pakiet Jetpack SDK stanowi wspólny punkt integracji zarówno pakietu APK Health Connect, jak i interfejsów API Health Connect.

Producenci OEM mogą zacząć integrować się z Jetpack 13, aby po udostępnieniu Jetpack 14 można było zastosować nową bibliotekę i skompilować ją w Androidzie 14.

Opublikujemy nową wersję pakietu SDK, która obsługuje przejście na Androida 14. Aby zapewnić płynne przejście, musisz wprowadzić pewne zmiany w dotychczasowej integracji.

Deklaracja uprawnień

W Androidzie 13 uprawnienia deklarujesz w niestandardowym formacie w pliku zasobu połączonym z pliku manifestu:

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

Aby zapewnić obsługę Androida 14, deweloperzy muszą przejść na standardowy format uprawnień:

#AndroidManifest.xml

<uses-permission android:name=android.permission.health.READ_SLEEP />
<uses-permission android:name=android.permission.health.READ_WEIGHT />
<uses-permission android:name=android.permission.health.WRITE_WEIGHT />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

Otwieranie Health Connect

Większość aplikacji innych firm ma przycisk, który otwiera aplikację Health Connect, np. przycisk „Zarządzaj dostępem” w Fitbicie.

Na Androidzie 13 możesz otworzyć aplikację Health Connect, używając nazwy pakietu lub akcji androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

W Androidzie 14 musisz użyć działania intencjonalnego określonego w pakiecie Jetpack SDK. Ma ono różne wartości w zależności od wersji Androida, w której działa:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

Pobieranie klienta Health Connect

Stworzyliśmy pojedynczy interfejs API o nazwie sdkStatus, dostępny w Jetpacku 11, aby zastąpić 2 inne wycofane interfejsy API: IsSdkSupported()isProviderAvailable().

Zmiany w interfejsie API rekordu sesji

W ramach wersji alpha10 usunięto 4 podtypy ExerciseSession:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Podobnie jak w przypadku ExerciseSessionRecord, SleepStage stanie się podtypem SleepSession.

Zarówno podtypy ExerciseSessionRecord, jak i zmiany SleepSession zostaną udostępnione w ramach kwietniowej aktualizacji pakietu SDK.

Aktualizacja typu sesji ćwiczeń

Te typy sesji ćwiczeń nie będą już obsługiwane, a zamiast tego zostaną dodane jako typy segmentów w późniejszym terminie:

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

Typy wymiany:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Obsługa historii zmian

W ramach przejścia z plików APK na Androida 14 nie zostaną przeniesione dzienniki zmian.

Po zakończeniu migracji zaczniesz otrzymywać wyjątki TOKEN_EXPIRED lub TOKEN_INVALID. Te pliki należy obsługiwać w taki sposób (w kolejności preferencji):

1. Odczytywanie i usuwanie duplikatów wszystkich danych od momentu ustawienia sygnatury czasowej „ostatniego odczytu” lub z ostatnich 30 dni

przechowywać sygnaturę czasową ostatniego odczytu danych z Health Connect przez aplikację; Po wygaśnięciu tokena dane powinny zostać ponownie odczytane z tej wartości lub z danych z poprzednich 30 dni (w zależności od tego, co jest minimalne) i zweryfikowane pod kątem duplikatów za pomocą identyfikatora UUID.

2. Odczytywanie danych od sygnatury czasowej „ostatniego odczytu”

Ustaw sygnaturę czasową, która wskazuje, kiedy dane zostały ostatnio odczytane z Health Connect. Po wygaśnięciu tokena odczytaj wszystkie dane po tej wartości.

3. Usuwanie i ponowne czytanie danych z ostatnich 30 dni

usunąć wszystkie dane odczytane z Health Connect z poprzednich 30 dni i ponownie odczytać wszystkie te dane (np. tak jak podczas pierwszej integracji aplikacji z Health Connect);

4. Nie rób nic (czyli ponownie odczytaj dane z ostatnich 30 dni i nie usuwaj duplikatów)

Należy używać tej opcji tylko w sytuacji, gdy inne metody zawiodły. Należy jednak pamiętać, że może to wiązać się z ryzykiem wyświetlania danych podwójnie. Deweloperzy powinni zamiast tego rozważyć opcje 1–3, ponieważ identyfikatory UUID powinny być już dostępne.

Testowanie interfejsów API Androida 14 za pomocą Jetpack SDK

Pakiet Jetpack SDK dla Androida 14 zostanie wydany 7 czerwca 2023 r. wraz z wersją beta 3 Androida 14. Aby móc używać pakietu Jetpack SDK na Androida 14, musisz skompilować aplikację pod kątem tego systemu operacyjnego.

Jeśli chcesz przetestować swoje rozwiązanie na wersjach Androida w wersji dla deweloperów przed 7 czerwca, skontaktuj się z osobą kontaktową w Google, aby uzyskać pomoc.

Jeśli chcesz przetestować swoje rozwiązanie w wersji Beta 3, w pliku APK musisz wprowadzić te zmiany:

  1. Ustaw compileSDKPreview = UpsideDownCake.
  2. Zaktualizuj plik manifestu, aby uwzględnić w nim intencję na potrzeby Androida 14:
# AndroidManifest.xml

<uses-permission android:name=android.permission.health.READ_SLEEP/>
<uses-permission android:name=android.permission.health.READ_WEIGHT/>
<uses-permission android:name=android.permission.health.WRITE_WEIGHT/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
      <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
      </intent-filter>
</activity-alias>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Personalizacja OEM

W Androidzie 14 ustawienia prywatności i zarządzania danymi w Health Connect znajdują się w ustawieniach systemu.

Aby ekrany zarządzania danymi i uprawnieniami wyglądały jak część urządzenia, Health Connect oferuje motywy OEM za pomocą niestandardowych nakładek.

Dokumentację na temat stylizacji OEM znajdziesz w dokumentacji Google Mobile Services w Health Connect. Aby wyświetlić tę stronę, musisz się zalogować w Google Developers.