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

Aplikacja Health Connect w pakiecie będzie zawierać Androida 14 jako wspólną warstwę do przechowywania danych dotyczących zdrowia konsumentów, chronioną dzięki szczegółowym uprawnieniom i dostępną jako aplikacja systemowa na Androida (w tym dokumencie nazywana jest modułem platformy).

Deweloperzy powinni traktować plik APK Health Connect (Android 13) jako warstwę zgodności wstecznej dla modelu platformy. Model platformy zachowa 100% spójności funkcji z poprzednim pakietem APK.

W okresie przechodzenia z Androida 13 na wersję 14 bardzo ważne jest, aby korzystanie z Androida było możliwie płynne i intuicyjne.

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

Plan migracji

  1. Po opublikowaniu Androida 14 Google będzie udostępniać Health Connect jako aplikację systemową na Androida.
  2. Po osiągnięciu spójności funkcji dane zostaną następnie uzupełnione z pliku APK.
  3. Wszystkie punkty wejścia będą kierowane na interfejs aplikacji systemowej.
  4. Rozpocznie się migracja danych. W trakcie migracji interfejsy API modułu zostaną zawieszone ze stanem „Migracja w toku”. Ta informacja będzie też widoczna w interfejsie Health Connect.
  5. Po zakończeniu migracji plik APK będzie można odinstalować.

Przykładowe scenariusze migracji

Oto kilka przykładowych scenariuszy, które wyjaśniają proces migracji typów danych interval i series:

Przykład 1 – bieganie (dane interwałowe)

Użytkownik zbiera rekordy biegu przez 10 lat dziennie przez 1 godzinę. Oznacza to:

  • Zapisy sesji ćwiczeń: 365 * 10 * 1
  • Kroki: 365 * 10 * 1
  • Kalorie: 365 * 10 * 1
  • Łącznie = 365 * 10 * 3 (365 * 30) = 10 150

Biorąc pod uwagę,że 1 fragment odpowiada 3000 rekordów, powyższe dane dają łącznie około 4 fragmentów.

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

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

Użytkownik zebrał dane dotyczące tętna z 5 lat (z rekordem tworzonym co minutę) i łącznie 2 628 000 zapisów.

Przy 3000 rekordów na fragment dane są rozłożone w 876 fragmentach. Ponieważ wstawienie 1 fragmentu zajmuje około sekundy, dane zostaną przeniesione w niecałe 15 minut.

Proponowany przepływ migracji

Zdecydowaliśmy się na migrację błyskawiczną. W praktyce oznacza to, że pakiet APK stanie się nieaktywny po uaktualnieniu urządzenia do Androida 14, przy minimalnej ingerencji użytkownika.

Przyjrzyjmy się ogólnemu procesowi migracji:

  1. użytkownik uaktualnia urządzenie do Androida 14.
  2. Jetpack 14 przekierowuje użytkownika do interfejsów API modułu i blokuje je podczas migracji.
  3. Proces migracji rozpoczyna się, gdy wersja modułu jest zgodna z pakietem APK – tzn. wersja modułu zawiera ten sam lub więcej funkcji. Po rozpoczęciu procesu migracji pakiet APK przeniesie uprawnienia i dane.
    1. Jeśli obie wersje nie są zgodne, konieczna będzie aktualizacja wersji modułu. Po zakończeniu uaktualniania rozpocznie się proces migracji.
  4. Po zakończeniu migracji stan zmienia się na „Migracja zakończona”, a interfejsy API modułu zostają odblokowane.
  5. Plik APK możesz teraz odinstalować.

Elementy interfejsu migracji

Poniższe ekrany są wyświetlane w module platformy w celach edukacyjnych, zarówno przed migracją, jak i w jej trakcie:

Rysunek 1. Jeśli pakiet APK Health Connect nie jest „podlega migracji”, wyświetlany jest komunikat z prośbą o zaktualizowanie pliku APK. Jeśli użytkownik odrzuci aktualizację, moduł nadal będzie działać i zaczyna gromadzić uprawnienia i dane:

Wymagana aktualizacja telefonu


Rysunek 2. Jeśli moduł platformy wymaga aktualizacji, aby był zgodny z funkcjami, pojawi się prośba o wykonanie 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. W trakcie procesu migracji wyświetlany jest wskaźnik postępu z tekstem wyjaśniającym, że dane są synchronizowane:

Synchronizacja danych

Deduplikowane dane

Jeśli moduł platformy zaczął zdobywać dane i uprawnienia przed przeprowadzeniem migracji lub przywracania w chmurze, obowiązują te reguły.

Uprawnienia

Jeśli moduł platformy zawiera uprawnienia, wszystkie zduplikowane uprawnienia uzyskane z pliku APK zostaną zignorowane podczas procesu migracji.

Dane

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

Jeśli identyfikator rekordu został dostarczony przez klienta, dane są usuwane z clientRecordId. Jeśli nie, przedziały czasu (startTime i endTime w przypadku rekordów wewnętrznych i time w przypadku rekordów błyskawicznych) są traktowane jako klucze razem z typem danych i nazwą pakietu aplikacji.

Zmiany w pakiecie SDK Jetpack

Pakiet Jetpack SDK jest wspólnym punktem integracji zarówno dla pakietu APK Health Connect, jak i interfejsów API platformy Health Connect.

Producenci OEM mogą zacząć integrować się z Jetpackiem 13, aby gdy pakiet Jetpack 14 stanie się dostępny, użytkownicy będą mogli pobrać nową bibliotekę i skompilować ją w Androidzie 14.

Wkrótce opublikujemy nową wersję pakietu SDK, która umożliwi przejście na Androida 14. Aby przejście przebiegło płynnie, musisz wprowadzić pewne zmiany w istniejącej integracji.

Deklaracja uprawnień

W Androidzie 13 uprawnienia deklarujesz przy użyciu niestandardowego formatu w pliku zasobów połączonym z plikiem 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 obsługiwać 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>

Otwórz Health Connect

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

W Androidzie 13 aplikację Health Connect możesz otworzyć, korzystając z nazwy pakietu, lub używając działania androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

W Androidzie 14 należy użyć działania intencji określonego w pakiecie SDK Jetpack. Może ono mieć różne wartości w zależności od używanej wersji Androida:

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

Uzyskiwanie klienta Health Connect

Utworzyliśmy pojedynczy interfejs API o nazwie sdkStatus dostępny w wersji Jetpack 11, który zastąpił 2 inne wycofane interfejsy API – IsSdkSupported() i isProviderAvailable().

Zmiany interfejsu API rekordu sesji

W ramach wersji alfa10 usunięto 4 podtypy ExerciseSession:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Podobnie jak ExerciseSessionRecord, SleepStage stanie się podtypem SleepSession.

W kwietniowej aktualizacji pakietu SDK zostaną udostępnione podtypy ExerciseSessionRecord i zmiany SleepSession.

Aktualizacja typu sesji ćwiczeń

Poniższe typy sesji ćwiczeń nie będą już obsługiwane, a w przyszłości dodamy je jako typy segmentów:

  • 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 zamienników:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Obsługa historii zmian

W ramach przechodzenia z pliku APK na Androida 14 nie zostaną przeniesione dzienniki zmian.

Po zakończeniu migracji zaczniesz otrzymywać wyjątki (TOKEN_EXPIRED lub TOKEN_INVALID). Należy je stosować w taki sposób (w kolejności od preferowanych):

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

Przechowuj sygnaturę czasową ostatniego odczytu danych z Health Connect przez aplikację. Po wygaśnięciu tokena dane należy ponownie odczytać na podstawie tej wartości lub z poprzednich 30 dni (w zależności od wartości minimalnej) i usunąć je z danych odczytanych wcześniej za pomocą identyfikatora UUID.

2. Odczytywanie danych od sygnatury czasowej ostatniego odczytu

Utwórz sygnaturę czasową, która wskazuje, kiedy dane były ostatnio odczytywane z Health Connect, a po wygaśnięciu tokena odczyt wszystkie dane po tej wartości.

3. Usuń i ponownie odczytaj dane z ostatnich 30 dni

Usuń wszystkie dane odczytywane z Health Connect z ostatnich 30 dni i ponownie je odczytaj (np. gdy aplikacja po raz pierwszy została zintegrowana z tą platformą).

4. niczego nie robić (czyli czytać dane z ostatnich 30 dni i nie usuwać duplikatów)

Tej opcji należy używać w ostateczności – wiąże się to z ryzykiem wyświetlenia zduplikowanych danych. Ponieważ identyfikatory UUID powinny już być dostępne, deweloperzy powinni zapoznać się z opcjami 1–3.

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

Pakiet SDK Jetpack na Androida 14 zostanie opublikowany 7 czerwca 2023 r. wraz z Androidem 14 w wersji beta 3. Aby korzystać z pakietu Android 14 Jetpack SDK, musisz zacząć kompilować aplikację do Androida 14.

Jeśli chcesz przetestować swoje rozwiązanie w porównaniu z kompilacjami w wersji przedpremierowej na Androida przed 7 czerwca, poproś o pomoc osobę kontaktową w Google.

Jeśli chcesz przetestować rozwiązanie w porównaniu z wersją beta 3, wprowadź te zmiany w pakiecie APK:

  1. Ustaw compileSDKPreview = UpsideDownCake.
  2. Dodaj do pliku manifestu intencję w przypadku 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>

Dostosowywanie OEM

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

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

Dokumentację dotyczącą stylu OEM znajdziesz w dokumentacji usług mobilnych Google Health Connect.