Rozszerzenia SDK

Rozszerzenia pakietu SDK wykorzystują modułowe komponenty systemu, aby dodawać interfejsy API do publicznego pakietu SDK dla 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 dla tych starszych wersji Androida.

Obsługa wersji 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 w określonej wersji. Na przykład interfejs API ACTION_PICK_IMAGES selektora zdjęć został dodany do publicznego pakietu SDK w Androidzie 13 (poziom API 33), ale jest też dostępny w rozszerzeniach pakietu SDK od wersji 2 rozszerzeń R. Nazwy rozszerzeń pakietu SDK odpowiadają stałej całkowitej – stałej z Build.VERSION_CODES lub stałej zdefiniowanej w klasie SdkExtensions (np. SdkExtensions.AD_SERVICES).

Określanie, których rozszerzeń pakietu SDK chcesz używać

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

Na stronach dokumentacji API rozszerzenia pakietu SDK podana jest najwcześniejsza wersja rozszerzenia pakietu SDK, której aplikacja może używać do uzyskiwania dostępu do interfejsu API. Jeśli w dokumentacji podano też wersję platformy Android (odniesienie do poziomu API), to 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 od Androida 13 (API na poziomie 33), ale jest też dostępny na urządzeniach z Androidem 11 (API na poziomie 30), o ile urządzenie ma co najmniej R Extensions w wersji 2:

Aby korzystać z tego interfejsu API, musisz skompilować aplikację z użyciem pakietu SDK na poziomie API 33 lub wyższym albo na poziomie rozszerzenia 2 lub wyższym.

Aby użyć pakietu SDK rozszerzenia:

1. Sprawdź minimalną wersję rozszerzeń, której potrzebujesz, w dokumentacji funkcji i dokumentacji interfejsu API, z których chcesz korzystać.
2. Po określeniu wymaganej wersji rozszerzenia dla zestawu funkcji otwórz narzędzie SDK Manager w Androidzie Studio.
3. Wybierz wpis Android SDK Platform z odpowiednią wersją rozszerzenia (lub wyższą, ponieważ interfejsy API są dodatkowe). Na przykład: Android SDK Platform 33, Extension Level 4.

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

   Dynamiczny

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   Kotlin

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

Sprawdzanie, czy rozszerzenia pakietu SDK są dostępne

Aplikacja może sprawdzać, które wersje rozszerzenia pakietu SDK są dostępne w czasie działania, a podczas tworzenia możesz wyszukiwać wersje rozszerzenia za pomocą poleceń Android Debug Bridge (adb), jak opisano w kolejnych sekcjach.

Sprawdzanie w czasie działania

Aplikacja może w czasie działania sprawdzić, czy rozszerzenia pakietu SDK są dostępne dla danej wersji platformy, korzystając z metody getExtensionVersion(). Na przykład ten kod sprawdzi, czy jest dostępna wersja 2 lub nowsza rozszerzenia pakietu SDK Androida 11 (interfejs API na poziomie 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 podstawie Build.VERSION.SDK_INT:

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

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

Ta SDK_INT weryfikacja jest nadal bezpieczna i prawidłowa, ale isPhotoPickerAvailable może zwracać wartość false na niektórych urządzeniach, nawet jeśli interfejs API rozszerzenia jest dostępny. W rezultacie SDK_INT weryfikacja nie jest optymalna, a sprawdzanie wersji rozszerzenia jest lepszym sposobem na sprawdzenie dostępności interfejsu API. Wszystkie urządzenia z wartością SDK_INT większą lub równą 33 (Android 13 lub nowszy) mają interfejsy API selektora zdjęć w publicznym pakiecie SDK, ale istnieją urządzenia z wartością SDK_INT mniejszą niż 33 (np. Android 11, 12 i 12L), które również mogą uzyskać dostęp do interfejsów API, jeśli mają wersje rozszerzenia R co najmniej 2.

W takim przypadku sprawdzenie wersji rozszerzenia może pomóc aplikacji w udostępnianiu dodatkowych funkcji większej liczbie użytkowników. Listę wszystkich stałych, których możesz użyć do sprawdzania, czy na urządzeniu są dostępne określone rozszerzenia SDK, znajdziesz w sekcji Nazwy i stałe rozszerzeń SDK.

Rozszerzenia usług reklamowych

Podobnie jak w przypadku ogólnego zestawu rozszerzeń pakietu SDK, AdServicesdokumentacja interfejsu API czasami wskazuje, że interfejs API jest częścią wersji „Rozszerzenia usług reklamowych”. W przeciwieństwie do ogólnych rozszerzeń pakietu SDK rozszerzenia usług reklamowych używają stałej SdkExtensions.AD_SERVICES do określania wersji 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 narzędziowe

W niektórych przypadkach rozszerzenia pakietu SDK mają metody narzędziowe Jetpack 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ść selektora zdjęć, która abstrahuje od warunkowych sprawdzeń wersji.

Pomoc dotycząca narzędzi

W Androidzie Studio Flamingo | 2022.2.1 lub nowszym narzędzie lint może skanować pod kątem problemów z wersjami rozszerzeń pakietu SDK w ramach sprawdzania NewAPI. Dodatkowo Android Studio może automatycznie generować prawidłowe sprawdzanie wersji interfejsów API uruchamianych za pomocą rozszerzeń pakietu SDK.

Nazwy i stałe rozszerzeń pakietu SDK

W tabeli poniżej znajdziesz informacje o tym, jak różne zestawy rozszerzeń pakietu SDK wymienione w dokumentacji API są powiązane ze stałymi, których aplikacja może używać do sprawdzania dostępności interfejsu API w czasie działania. Ogólny zestaw rozszerzeń pakietu SDK dla każdego publicznego pakietu SDK jest mapowany na wartości Build.VERSION_CODES.

Sprawdzanie 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 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, które jest obecne na urządzeniu, oraz jego wersję (w tym przypadku 3).