Rozszerzenia SDK

Rozszerzenia pakietu SDK korzystają z modułowego systemu komponentów, aby dodawać interfejsy API do publicznego pakietu SDK w przypadku niektórych wcześniej opublikowanych poziomów interfejsu API. Te interfejsy API są dostarczane na urządzenia, gdy użytkownicy otrzymują aktualizacje modułów w ramach aktualizacji systemu Google Play. Deweloperzy aplikacji mogą używać tych interfejsów API w swoich aplikacjach, aby udostępniać dodatkowe funkcje, które nie były pierwotnie dostępne w pakiecie SDK w poprzednich wersjach Androida.

Wersje interfejsu API

Od Androida 11 (poziom API 30) urządzenia z Androidem zawierają zestaw rozszerzeń pakietu SDK. Gdy dodawane są nowe interfejsy API, są one uwzględniane na poziomie interfejsu API, ale mogą też być uwzględniane w rozszerzeniu pakietu SDK danej wersji. Na przykład interfejs API ACTION_PICK_IMAGES do selektora zdjęć został dodany do publicznego pakietu SDK w Androidzie 13 (poziom interfejsu API 33), ale jest też dostępny w rozszerzeniach pakietu SDK, począwszy od wersji 2 rozszerzeń R. Nazwy rozszerzeń pakietu SDK odpowiadają stałej liczbowej – stałej z Build.VERSION_CODES lub zdefiniowanej w klasie SdkExtensions (np. SdkExtensions.AD_SERVICES).

Wybieranie rozszerzeń pakietu SDK

Zanim zaczniesz używać interfejsów API rozszerzeń SDK, musisz najpierw określić, które pakiety SDK zawierają interfejsy API obsługujące przypadki użycia Twojej aplikacji.

Na stronach referencyjnych interfejsów API rozszerzeń pakietu SDK podano najstarszą wersję rozszerzenia pakietu SDK, której Twoja aplikacja może użyć do uzyskania dostępu do interfejsu API. Jeśli dokumentacja określa również wersję platformy Androida (odwołującą się do poziomu interfejsu API), oznacza to, że interfejs API jest dostępny na wszystkich urządzeniach z tą wersją Androida lub nowszą.

Na przykład funkcja ACTION_PICK_IMAGES jest ogólnie dostępna w publicznym pakiecie SDK od Androida 13 (poziom interfejsu API 33), ale jest też dostępna na urządzeniach z Androidem 11 (poziom interfejsu API 30), o ile mają co najmniej R Extensions w wersji 2:

Aby korzystać z tego interfejsu API, musisz skompilować kod z pakietem SDK na poziomie co najmniej 33 lub rozszerzenia na poziomie co najmniej 2.

Aby korzystać z SDK rozszerzenia:

1. Aby sprawdzić minimalną wymaganą wersję rozszerzeń, zapoznaj się z dokumentacją funkcji i dokumentacją referencyjną interfejsów API, których chcesz użyć.
2. Po określeniu wymaganej wersji rozszerzenia dla zestawu funkcji otwórz Menedżera pakietu SDK w Android Studio.
3. Wybierz pozycję Platforma pakietu SDK Androida z odpowiednią wersją rozszerzenia (lub nowszą, ponieważ interfejsy API są addytywne). Przykład: Android SDK Platforma 33, Extension Level 4.

4. Zadeklaruj te wartości w pliku build.gradle.kts lub build.gradle aplikacji:

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }
   

Sprawdzanie, czy rozszerzenia SDK są dostępne

Aplikacja może sprawdzić, jakie wersje rozszerzeń pakietu SDK są dostępne w czasie wykonywania. Podczas tworzenia możesz sprawdzić wersje rozszerzeń za pomocą poleceń Android Debug Bridge (adb), jak opisano w następnych sekcjach.

Sprawdzanie w czasie działania

Aplikacja może sprawdzić w czasie działania, czy rozszerzenia pakietu SDK są dostępne w przypadku danej wersji platformy, korzystając z metody getExtensionVersion(). Na przykład ten kod sprawdza, czy dostępna jest wersja 2 lub nowsza rozszerzenia pakietu SDK na Androida 11 (poziom interfejsu API 30):

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

Jest to podobne do sprawdzania na podstawieBuild.VERSION.SDK_INT:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

To sprawdzenie SDK_INT jest nadal bezpieczne i prawidłowe, ale na niektórych urządzeniach funkcja isPhotoPickerAvailable zwróci wartość false, mimo że interfejs API rozszerzenia jest dostępne. W rezultacie sprawdzenie SDK_INT nie jest optymalne, a sprawdzenie wersji rozszerzenia jest lepszym sposobem na sprawdzenie dostępności interfejsu API. Wszystkie urządzenia z SDK_INT większym lub równym 33 (Android 13 lub nowszy) mają interfejsy API selektora zdjęć w publicznym pakiecie SDK, ale istnieją też urządzenia z SDK_INT mniejszym niż 33 (np. Android 11, 12 i 12L), które mogą uzyskać dostęp do interfejsów API, jeśli mają wersję rozszerzenia R co najmniej 2.

W takim przypadku sprawdzenie wersji rozszerzenia może pomóc aplikacji w dostarczaniu dodatkowych funkcji większej liczbie użytkowników. Na stronie Nazwy i konstante rozszerzeń SDK znajdziesz listę wszystkich stałych, których możesz używać do sprawdzania obecności określonych rozszerzeń SDK na urządzeniu.

Rozszerzenia usług reklamowych

Podobnie jak w przypadku ogólnego zestawu rozszerzeń pakietu SDK, odwołanie do interfejsu API AdServices czasami wskazuje, że interfejs API jest częścią wersji „Rozszerzenia Ad Services”. W odróżnieniu od ogólnych rozszerzeń pakietu SDK rozszerzenia usług reklamowych korzystają z konstantej wartości SdkExtensions.AD_SERVICES, aby określić, która wersja jest na urządzeniu:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Więcej informacji o funkcjach rozszerzeń usług reklamowych i o tym, jak zacząć z nich korzystać, znajdziesz w dokumentacji rozszerzeń usług reklamowych.

Metody pomocnicze

W niektórych przypadkach rozszerzenia pakietu SDK mają metody narzędzia Jetpack służące do sprawdzania dostępności interfejsów API rozszerzeń pakietu SDK. Możesz na przykład użyć funkcji biblioteki Jetpacka, aby sprawdzić dostępność selektora zdjęć, co pozwala pominąć sprawdzanie wersji warunkowych.

Pomoc dotycząca narzędzi

W Android Studio Flamingo 2022.2.1 lub nowszej narzędzie lint może skanować wersje pakietu SDK Extension pod kątem problemów w ramach sprawdzania nowych interfejsów API. Dodatkowo Android Studio może automatycznie generować poprawne weryfikacje wersji interfejsów API uruchamianych za pomocą rozszerzeń pakietu SDK.

Nazwy i konstante rozszerzenia pakietu SDK

W tabeli poniżej opisano, jak różne zestawy rozszerzeń pakietu SDK wymienione w dokumentacji interfejsu API odnoszą się do stałych wartości, których aplikacja może używać do sprawdzania dostępności interfejsu API w czasie wykonywania. Ogólny zestaw rozszerzeń pakietu SDK dla każdego publicznego pakietu SDK jest mapowany na wartości Build.VERSION_CODES.

Sprawdzanie za pomocą adb

Aby sprawdzić, które rozszerzenia pakietu SDK są dostępne na urządzeniu za pomocą adb, uruchom to polecenie:

adb shell getprop | grep build.version.extensions

Po wykonaniu polecenia zobaczysz dane wyjściowe podobne do tych:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

Każdy wiersz zawiera rozszerzenie pakietu SDK obecne na urządzeniu wraz z odpowiednią wersją rozszerzenia (w tym przypadku 3).