Rozszerzenia SDK

Rozszerzenia SDK wykorzystują system modułowy Komponenty, aby dodać interfejsy API do publicznego pakietu SDK dla określonych wcześniej udostępnionych poziomów API. Te interfejsy API są dostarczane na urządzenia, gdy użytkownicy otrzymują aktualizacje modułów przez Google Play system aktualizacje. Promująca aplikację programistów mogą używać tych interfejsów API w swoich aplikacjach, funkcje, które nie były pierwotnie dostępne w pakiecie SDK wersji Androida.

Obsługa wersji interfejsu API

Począwszy od Androida 11 (poziom interfejsu API 30) urządzenia z Androidem zawierają zestaw SDK Rozszerzenia. Dodane nowe interfejsy API są uwzględniane na poziomie interfejsu API, ale mogą być również uwzględnione w rozszerzeniu SDK w konkretnej wersji. Na przykład parametr ACTION_PICK_IMAGES Interfejs API selektora zdjęć został dodany do publicznego pakietu SDK w Androidzie 13 (poziom API 33). lecz jest również dostępna w ramach rozszerzeń SDK w wersji 2 rozszerzeń R. Nazwy rozszerzeń pakietu SDK odpowiadają stałej liczbie całkowitej: stała od Build.VERSION_CODES lub 1 zdefiniowane w klasie SdkExtensions (np. SdkExtensions.AD_SERVICES).

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

Zanim zaczniesz używać interfejsów API rozszerzeń SDK, musisz określić, które pakiety SDK uwzględnij interfejsy API, które obsługują zastosowania aplikacji.

Strony z informacjami o interfejsach API rozszerzeń SDK określają najwcześniejszy pakiet SDK wersję rozszerzenia, której aplikacja może używać, aby uzyskać dostęp do interfejsu API. Jeśli dokumentacja określa też wersję platformy Androida (odwołaną od poziomu interfejsu API), to Interfejs API jest też dostępny dla wszystkich urządzeń z Androidem w tej wersji lub nowszej.

Na przykład pakiet ACTION_PICK_IMAGES jest ogólnie dostępny w publicznym pakiecie SDK. od Androida 13 (poziom interfejsu API 33), ale jest również dostępny na urządzeniach od Androida 11 (poziom interfejsu API 30), o ile urządzenie ma co najmniej R Wersja 2 rozszerzeń:

Aby korzystać z tego interfejsu API, musisz skompilować go pod kątem pakietu SDK na poziomie co najmniej API 33 lub Rozszerzenie na poziomie co najmniej 2.

Aby użyć pakietu SDK rozszerzenia, wykonaj te czynności:

1. Zaznacz funkcję, aby znaleźć minimalną wersję rozszerzenia, której potrzebujesz. dokumentacji i API interfejsów API, których chcesz używać.
2. Po określeniu wymaganej wersji rozszerzenia dla zestawu funkcji otwórz Menedżera pakietów SDK w Android Studio.
3. Wybierz wpis Android SDK Platform z odpowiednim rozszerzeniem (lub wyższa, ponieważ interfejsy API się sumują). Na przykład: Android SDK Platform 33, poziom rozszerzenia 4.

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

   Odlotowe

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

Sprawdzanie, czy są dostępne rozszerzenia SDK

aplikacja może sprawdzić, jakie wersje rozszerzenia pakietu SDK są dostępne w czasie działania; w trakcie tworzenia aplikacji, możesz sprawdzić jej wersje za pomocą narzędzia Android Debug Polecenia Bridge (adb) opisane w kolejnych sekcjach.

Sprawdź w czasie działania

Aplikacja może sprawdzić w czasie działania, czy w danym przypadku są dostępne rozszerzenia pakietu SDK wersji platformy za pomocą getExtensionVersion() . Na przykład ten kod sprawdza, czy rozszerzenie w wersji 2 Rozszerzenie SDK na Androida 11 (poziom API 30) lub nowsze jest dostępne:

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;
}

Przypomina to sprawdzanie 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 weryfikacja SDK_INT jest nadal bezpieczna i ważna, ale isPhotoPickerAvailable zwraca wartość false (fałsz) na niektórych urządzeniach, chociaż jest dostępny interfejs API rozszerzenia. Jako test SDK_INT nie jest optymalny, a sprawdzenie wersji rozszerzenia jest to lepszy sposób sprawdzenia dostępności interfejsu API. Wszystkie urządzenia z pakietem SDK_INT większą lub równe 33 (Android 13 lub nowszy) mają interfejsy API selektora zdjęć w publicznego pakietu SDK, ale są też urządzenia z SDK_INT w wersji starszej niż 33 (np. z Androidem) 11, 12 i 12L), które mogą również uzyskać dostęp do interfejsów API, jeśli mają rozszerzenie R co najmniej 2 w wersjach.

W takim przypadku sprawdzanie wersji rozszerzenia może pomóc w dostarczaniu aplikacji dostęp do dodatkowych funkcji większej liczbie użytkowników. Zobacz Nazwy rozszerzeń SDK oraz stałych, by otrzymać listę wszystkich stałych, których możesz użyć do sprawdzania określonych rozszerzeń SDK na urządzeniu.

Rozszerzenia usług reklamowych

Podobnie jak w przypadku ogólnego zestawu rozszerzeń SDK, dokumentacja API AdServices czasem wskazuje, że interfejs API jest częścią „rozszerzeń usług reklamowych” wersji. W przeciwieństwie do ogólnych rozszerzeń SDK, rozszerzenia usług reklamowych korzystają z Stała SdkExtensions.AD_SERVICES, która określa, która wersja jest zainstalowana 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;
}

Aby dowiedzieć się więcej o funkcjach rozszerzeń usług reklamowych i o tym, jak uzyskać zapoznaj się z sekcją Rozszerzenia usług reklamowych dokumentacji.

Metody użyteczności

W niektórych przypadkach rozszerzenia SDK korzystają z metod narzędziowych Jetpack do sprawdzania dostępność interfejsów API rozszerzeń SDK. Możesz na przykład użyć usługi Jetpack funkcja biblioteki do sprawdzenia pod kątem PhotoPicker dostępność, co wyodrębnia sprawdzanie wersji warunkowej.

Pomoc dotycząca narzędzi

W Android Studio Flamingo | wersji 2022.2.1 lub nowszej, narzędzie Lint może znaleźć problemów z wersjami rozszerzenia SDK w ramach testu NewAPI. Ponadto Android Studio może automatycznie generować prawidłowe testy wersji dla interfejsów API, które uruchomiono za pomocą rozszerzeń SDK.

Nazwy i stałe rozszerzenia pakietu SDK

W tabeli poniżej opisujemy, jak różne zestawy rozszerzeń SDK, które są wymienione w dokumentacji referencyjnej API na stałe, których może używać aplikacja sprawdzić dostępność interfejsu API w czasie działania aplikacji. Ogólny zestaw rozszerzeń SDK dla każdy publiczny pakiet SDK jest mapowany na wartości Build.VERSION_CODES

Sprawdź za pomocą narzędzia adb

Aby za pomocą narzędzia adb sprawdzić, które rozszerzenia pakietu SDK są dostępne na urządzeniu, uruchom polecenie 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

W każdym wierszu wyświetla się rozszerzenie SDK dostępne na urządzeniu, odpowiedniej wersji rozszerzenia (w tym przypadku 3).