Zgodność wsteczna środowiska wykonawczego SDK

W tym dokumencie proponujemy nową bibliotekę Jetpack, która pomoże deweloperom w migracji do środowiska wykonawczego SDK. Wyjaśnia, jak środowisko wykonawcze SDK będzie obsługiwane w przypadku poprzednich wersji platformy Android (od kompilacji po wykonanie) oraz jakich różnic lub ograniczeń w środowisku wykonawczym mogą spodziewać się deweloperzy. Ta biblioteka umożliwia deweloperom tworzenie jednej wersji aplikacji lub pakietu SDK, która może działać na urządzeniach z obsługą środowiska wykonawczego SDK i bez niej.

Zgodność wsteczna jest osiągana dzięki tym komponentom:

  • Wtyczka Androida do Gradle (AGP) i narzędzie Bundletool tworzą wariant aplikacji na urządzenia bez obsługi środowiska wykonawczego pakietu SDK, dołączając to środowisko do pliku APK.

  • Biblioteka klienta środowiska wykonawczego SDK (androidx.privacysandbox.sdkruntime:sdkruntime-client) wczytuje pakiet SDK z zasobów aplikacji i emuluje środowisko wykonawcze SDK na urządzeniach, które go nie obsługują.

  • Biblioteka dostawcy środowiska wykonawczego pakietu SDK (androidx.privacysandbox.sdkruntime:sdkruntime-provider) udostępnia interfejs API, który umożliwia pakietom SDK wczytywanie danych z biblioteki klienta środowiska wykonawczego pakietu SDK.

Dostarczanie pakietu SDK za pomocą narzędzia Bundletool

Na urządzeniach obsługujących środowisko wykonawcze pakietu SDK pakiety SDK będą dostarczane i instalowane jako oddzielne pakiety.

Aby obsługiwać wersje platformy, które nie obsługują środowiska wykonawczego pakietu SDK, narzędzie Bundletool utworzy co najmniej 1 wariant zestawu plików APK aplikacji, który będzie zawierać wszystkie pakiety SDK, od których zależy aplikacja. Każdy pakiet SDK jest pakowany jako osobny plik APK. Ponadto wykonywane są te przekształcenia:

  1. Skopiuj pliki kodu bajtowego SDK (DEX) do podziału SDK jako zasoby.
  2. Skopiuj zasoby pakietu SDK Java do podziału pakietu SDK jako zasoby.
  3. Zmień mapowanie zasobów pakietu SDK i scal je z zasobami aplikacji.
  4. Generowanie konfiguracji biblioteki klienta środowiska wykonawczego pakietu SDK.

Wczytywanie pakietów SDK za pomocą biblioteki klienta środowiska wykonawczego SDK

Biblioteka klienta środowiska wykonawczego pakietu SDK udostępnia interfejsy API podobne do interfejsów API platformy, ale obsługuje zarówno pakiety SDK w środowisku wykonawczym pakietu SDK, jak i pakiety SDK dołączone do aplikacji wariantu.

Aby użyć biblioteki klienta środowiska wykonawczego SDK, dodaj zależność androidx.privacysandbox.sdkruntime:sdkruntime-client i użyj SdkSandboxManagerCompat zamiast SdkSandboxManager.

Gdy aplikacja próbuje wczytać pakiet SDK, biblioteka najpierw sprawdza, czy pakiet SDK został dołączony do aplikacji podczas kompilacji. Jeśli biblioteka została dołączona, wyodrębnia pakiet SDK z podziału pakietu SDK i wczytuje go do procesu aplikacji. Jeśli pakiet SDK nie został dołączony do aplikacji, biblioteka przekazuje interfejs API platformy w celu wczytania pakietu SDK.

Wyodrębnianie pakietu SDK z komponentów

Gdy aplikacja próbuje wczytać pakiet SDK, biblioteka klienta środowiska wykonawczego SDK sprawdza, czy pliki DEX pakietu SDK zostały już wyodrębnione do pamięci urządzenia (code_cache). Jeśli nie, wyodrębnia je z zasobów.

Biblioteka zwykle wyodrębnia pliki tylko raz po zainstalowaniu lub zaktualizowaniu aplikacji.

Jeśli dostępna ilość miejsca na dane jest mniejsza niż dozwolony próg (obecnie 100 MB) i nie wyodrębniono żadnych plików DEX, biblioteka próbuje wczytać pakiet SDK bezpośrednio z zasobów na obsługiwanych urządzeniach (API w wersji 27 lub nowszej). Powoduje to większe zużycie pamięci.

Ładowarka klas dla klas pakietu SDK

Aby uniknąć konfliktów między pakietami SDK a klasami aplikacji, wszystkie klasy pakietu SDK są wczytywane za pomocą oddzielnego modułu wczytywania klas, który jest całkowicie niezależny od modułu wczytywania klas głównej aplikacji.

W obecnej wersji środowiska wykonawczego SDK cała komunikacja między aplikacją a pakietami SDK odbywa się za pomocą wywołań IPC Binder. W przypadku pakietów SDK są używane te same obiekty Binder SDK, a serializacja transakcji Binder umożliwia deweloperom aplikacji rzutowanie obiektów Binder SDK na interfejsy Binder SDK po stronie aplikacji.

W przypadku innych interakcji wewnętrznych (np. inicjowania pakietu SDK, udostępniania interfejsu API kontrolera pakietowi SDK itp.) biblioteka używa odbicia i dynamicznych serwerów proxy, aby działać w różnych programach ładujących klasy.

Środowisko pakietu SDK

Biblioteka dostawcy SDKRuntime udostępnia interfejsy API deweloperom pakietów SDK. Te interfejsy API są podobne do interfejsów API platformy, ale umożliwiają wczytywanie pakietów SDK zarówno przez środowisko wykonawcze pakietu SDK, jak i bibliotekę klienta środowiska wykonawczego pakietu SDK.

Aby móc korzystać z pakietu SDK biblioteki, musisz dodać zależność androidx.privacysandbox.sdkruntime:sdkruntime-provider i rozszerzyć SandboxedSdkProviderCompat zamiast SandboxedSdkProvider.

Musisz też używać SandboxedSdkProviderAdapter jako dostawcy pakietu SDK, aby umożliwić wczytanie dostawcy zgodności w środowisku wykonawczym pakietu SDK.

SdkSandboxControllerCompat przekazuje wywołanie do interfejsu API platformy, gdy pakiet SDK jest wczytany w środowisku wykonawczym pakietu SDK, lub do biblioteki klienta środowiska wykonawczego pakietu SDK, gdy pakiet SDK jest wczytany jako pakiet dołączony.

W przypadku pakietów SDK w pakiecie biblioteka modyfikuje środowisko SDK w sposób, który emuluje zachowanie podobne do środowiska wykonawczego SDK.

W kolejnych sekcjach opisujemy oczekiwane zachowania, gdy pakiet SDK jest wczytywany przez bibliotekę klienta SDKRuntime.

Materiały dotyczące pakietu SDK

Zasoby pakietu SDK (res/) są obsługiwane, gdy pakiet SDK jest wczytywany w procesie aplikacji. Narzędzie Bundletool łączy wszystkie zasoby pakietów SDK z zasobami aplikacji.

Aby uniknąć konfliktów, zasoby pakietu SDK są ponownie mapowane przez zmianę prefiksu packageIdwe wszystkich identyfikatorach zasobów.

Gdy pakiet SDK zostanie wczytany przez bibliotekę klienta SDKRuntime, wartość packageId zostanie zaktualizowana w środowisku wykonawczym, aby umożliwić odwoływanie się do zmapowanych zasobów za pomocą klasy R.

Zasoby dotyczące Javy

Zasoby Java są obsługiwane, gdy pakiet SDK jest wczytywany w procesie aplikacji. Narzędzie Bundletool kopiuje wszystkie zasoby Javy pakietu SDK do specjalnego katalogu w zasobach aplikacji. Biblioteka klienta SDKRuntime używa pośredniego modułu ładującego klasy, aby przekierowywać wszystkie wywołania związane z zasobami Java do nowego katalogu głównego.

Zasoby pakietu SDK

Komponenty pakietu SDK są scalane z komponentami aplikacji bez ponownego mapowania.

Miejsce na dysku SDK

Aby obsługiwać pamięć SDK, biblioteka klienta środowiska wykonawczego SDK tworzy w pamięci aplikacji dedykowany katalog główny dla każdego pakietu SDK dołączonego do aplikacji i udostępnia specjalny kontekst, który używa tego katalogu jako katalogu głównego pamięci.

Ten kontekst można pobrać z SandboxedSdkProviderCompat#getContext.

Obsługiwane metody związane z miejscem na dane:

  • getDataDir
  • getCacheDir
  • getCodeCacheDir
  • getNoBackupFilesDir
  • getDir
  • getFilesDir
  • openFileInput
  • openFileOutput
  • deleteFile
  • getFileStreamPath
  • fileList
  • getDatabasePath
  • openOrCreateDatabase
  • moveDatabaseFrom – tylko w kontekstach pakietu SDK
  • deleteDatabase
  • databaseList
  • getSharedPreferences
  • moveSharedPreferencesFrom – tylko w kontekstach pakietu SDK
  • deleteSharedPreferences

Kontekst pamięci chronionej urządzenia można utworzyć, wywołując w nim funkcję createDeviceProtectedStorageContext().

SdkSandboxControllerCompat

Biblioteka klienta SDKRuntime udostępnia implementację SdkSandboxControllerCompat dla pakietów SDK dołączonych do procesu aplikacji.

Jeśli interfejsy API nie są obsługiwane przez bibliotekę klienta (np. w przypadku pakietu SDK utworzonego w wersji biblioteki nowszej niż wersja aplikacji), zostanie użyte najbardziej odpowiednie rozwiązanie zastępcze (brak działania lub wyjątek).

Obsługa wersji

Gdy biblioteka klienta SDKRuntime wczytuje pakiet SDK, przeprowadza uzgadnianie z biblioteką dostawcy SDKRuntime w pakiecie SDK. Podczas uzgadniania połączenia biblioteki wymieniają się wersjami i dostosowują działanie, aby zastąpić niedostępne interfejsy API najbardziej odpowiednim rozwiązaniem zastępczym (bez operacji lub wyjątek).

Zarówno deweloperom aplikacji, jak i dostawcom SDK zdecydowanie zalecamy korzystanie z najnowszej wersji biblioteki. W przeciwnym razie funkcje, które wymagają obsługi w obu częściach, mogą być niedostępne.

Każda wersja biblioteki klienta SDKRuntime może wczytać pakiet SDK z dowolną wersją biblioteki dostawcy SDKRuntime i na odwrót.

W przyszłości zostanie to zmienione na minimalną wersję biblioteki klienta wymaganą do wczytania pakietu SDK z określoną wersją biblioteki dostawcy.

Zminimalizuje to fragmentację i pomoże zapewnić obsługę większości interfejsów API, jeśli pakiet SDK zostanie prawidłowo wczytany.