Rozszerzenia pakietów SDK wykorzystują modułowe komponenty systemowe do dodawania interfejsów API do publicznego pakietu SDK na określonych wcześniej poziomach. Te interfejsy API są dostarczane do urządzeń, 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.
Obsługa wersji interfejsu API
Począwszy od Androida 11 (poziom interfejsu API 30), urządzenia z Androidem zawierają zestaw rozszerzeń SDK. Dodane nowe interfejsy API są uwzględniane na poziomie interfejsu API, ale mogą być też uwzględnione w rozszerzeniu pakietu SDK w konkretnej wersji. Na przykład interfejs ACTION_PICK_IMAGES
API dla selektora zdjęć został dodany do publicznego pakietu SDK w Androidzie 13 (poziom API 33), ale od wersji 2 rozszerzeń R jest też dostępny za pomocą rozszerzeń SDK.
Nazwy rozszerzeń SDK odpowiadają stałej liczbie całkowitej – stałej z Build.VERSION_CODES
lub określonej w klasie SdkExtensions
(np. SdkExtensions.AD_SERVICES
).
Określanie, których rozszerzeń SDK używać
Zanim użyjesz interfejsów API rozszerzeń pakietów SDK, musisz najpierw określić, które pakiety SDK zawierają interfejsy API obsługujące Twoją aplikację.
Na stronach z dokumentacją API dla interfejsów API rozszerzeń pakietu SDK określono najwcześniejszą wersję rozszerzenia pakietu SDK, za pomocą której aplikacja może uzyskiwać dostęp do interfejsu API. Jeśli w dokumentacji podana jest również wersja platformy Androida (do której odwołuje się poziom interfejsu API), oznacza to, że ten interfejs API jest też dostępny na wszystkich urządzeniach z tą wersją Androida lub nowszą.
Na przykład ACTION_PICK_IMAGES
jest ogólnie dostępny w publicznym pakiecie SDK zaczynającym się od Androida 13 (poziom interfejsu API 33), ale można z niego też korzystać na urządzeniach starszych niż Android 11 (poziom interfejsu API 30), o ile urządzenie ma co najmniej rozszerzenia R w wersji 2:
Aby korzystać z tego interfejsu API, musisz skompilować go do pakietu SDK, który ma co najmniej poziom 33 interfejsu API lub co najmniej 2.
Aby skorzystać z pakietu SDK rozszerzeń:
- Sprawdź minimalną wersję rozszerzeń, której potrzebujesz, sprawdzając dokumentację funkcji i dokumentację API interfejsów API, których chcesz użyć.
- Gdy określisz wymaganą wersję rozszerzenia dla zbioru funkcji, otwórz SDK Manager w Android Studio.
- Wybierz pozycję Android SDK Platform z odpowiednią wersją rozszerzenia (lub wyższą, ponieważ interfejsy API się sumują). np.: Android SDK Platform 33, rozszerzenie poziomu 4.
Zadeklaruj te wartości w pliku
build.gradle.kts
lubbuild.gradle
aplikacji:Odlotowy
android { compileSdk 33 compileSdkExtension 4 ... }
Kotlin
android { compileSdk = 33 compileSdkExtension = 4 ... }
Sprawdzanie, czy są dostępne rozszerzenia pakietu SDK
Aplikacja może sprawdzać, jakie wersje rozszerzeń SDK są dostępne w czasie działania, a w trakcie jej tworzenia możesz sprawdzać ich wersje za pomocą poleceń Android Debug Bridge (adb) zgodnie z opisem w kolejnych sekcjach.
Sprawdź w czasie działania
Aplikacja może za pomocą metody getExtensionVersion()
sprawdzić w czasie działania, czy rozszerzenia pakietu SDK są dostępne w przypadku danej wersji platformy. Na przykład ten kod sprawdzi, czy jest dostępne rozszerzenie w wersji 2 lub nowszej w przypadku rozszerzenia pakietu SDK na Androida 11 (poziom interfejsu API 30) i jego dostępności:
Kotlin
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. }
Java
public static final boolean isPhotoPickerAvailable() { return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2; }
Przypomina to sprawdzanie na podstawie Build.VERSION.SDK_INT
:
Kotlin
fun isPhotoPickerAvailable(): Boolean { return Build.VERSION.SDK_INT >= 33 }
Java
public static final boolean isPhotoPickerAvailable() { return Build.VERSION.SDK_INT >= 33; }
Ten test SDK_INT
jest nadal bezpieczny i prawidłowy, ale isPhotoPickerAvailable
zwróci na niektórych urządzeniach wartość „false”, mimo że interfejs API rozszerzenia jest dostępny. W efekcie sprawdzanie SDK_INT
nie jest optymalne, a sprawdzanie wersji rozszerzenia stanowi lepszy sposób sprawdzania dostępności interfejsu API. Wszystkie urządzenia z SDK_INT
w wersji 33
lub wyższej (Android 13 lub nowszy) mają interfejsy API selektora zdjęć w publicznym pakiecie SDK, ale istnieją urządzenia z SDK_INT
w wersji starszej niż 33 (np. Android 11, 12 i 12L), które również mają dostęp do interfejsów API w wersji R co najmniej 2
.
W takim przypadku sprawdzenie wersji rozszerzenia może pomóc w udostępnieniu dodatkowych funkcji większej liczbie użytkowników. Listę wszystkich stałych, których możesz używać do sprawdzania określonych rozszerzeń SDK na urządzeniu, znajdziesz w sekcji Nazwy i stałe rozszerzenia pakietu SDK.
Rozszerzenia usług reklamowych
Podobnie jak w przypadku ogólnego zestawu rozszerzeń SDK, informacje o interfejsie API AdServices
czasami wskazują, że interfejs API jest częścią wersji „Rozszerzenia usług reklamowych”.
W przeciwieństwie do ogólnych rozszerzeń w pakiecie SDK rozszerzenia usług reklamowych używają stałej SdkExtensions.AD_SERVICES
do określenia, która wersja znajduje się na urządzeniu:
Kotlin
fun isAdServicesAvailable(): Boolean { return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4 }
Java
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 użyteczności
W niektórych przypadkach rozszerzenia pakietów SDK mają 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 Jetpack, aby sprawdzić dostępność PhotoPicker, co pozwoli uniknąć sprawdzania wersji warunkowej.
Pomoc dotycząca narzędzi
W Android Studio Flamingo | 2022.2.1 lub nowszym narzędzie Lint może w ramach kontroli NewAPI skanować pod kątem problemów z wersjami rozszerzenia pakietu SDK. Dodatkowo Android Studio może automatycznie generować poprawne testy wersji interfejsów API uruchamianych za pomocą rozszerzeń w pakiecie SDK.
Nazwy i stałe rozszerzenia pakietu SDK
W tabeli poniżej opisujemy, jak różne zestawy rozszerzeń SDK wymienione w dokumentacji referencyjnej interfejsu API są mapowane na stałe, których aplikacja może używać do sprawdzania dostępności interfejsu API w czasie działania. Ogólny zestaw rozszerzeń SDK dla każdego publicznego pakietu SDK jest mapowany na wartości Build.VERSION_CODES
.
Nazwa rozszerzenia pakietu SDK | Stała | Kwalifikujące się urządzenia |
---|---|---|
Rozszerzenia R | VERSION_CODES.R |
Android 11 (poziom API 30) i nowsze |
Rozszerzenia S | VERSION_CODES.S |
Android 12 (poziom API 31) i nowsze |
Rozszerzenia T | VERSION_CODES.TIRAMISU |
Android 13 (poziom interfejsu API 33) i nowszy |
Rozszerzenia usług reklamowych | SdkExtensions.AD_SERVICES |
Android 13 (poziom interfejsu API 33) i nowszy |
Sprawdź za pomocą narzędzia 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 uruchomieniu polecenia wyświetlą się 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 SDK obecne na urządzeniu wraz z odpowiadającą im wersją rozszerzenia (w tym przypadku 3).