Расширения SDK используют модульные системные компоненты для добавления API в общедоступный SDK для определенных ранее выпущенных уровней API. Эти API доставляются на устройства, когда конечные пользователи получают обновления модулей через обновления системы Google Play . Разработчики приложений могут использовать эти API в своих приложениях для предоставления дополнительных функций, которые изначально не были доступны в SDK для предыдущих версий Android.
Управление версиями API
Начиная с Android 11 (уровень API 30), устройства Android включают набор расширений SDK. Когда добавляются новые API, они включаются в уровень API, но также могут быть включены в расширение SDK определенной версии. Например, API ACTION_PICK_IMAGES
для средства выбора фотографий был добавлен в общедоступный SDK в Android 13 (уровень API 33), но также доступен через расширения SDK, начиная с R Extensions версии 2. Имена расширений SDK соответствуют целочисленной константе — либо константе из Build.VERSION_CODES
или определенного в классе SdkExtensions
(например, SdkExtensions.AD_SERVICES
).
Определите, какие расширения SDK использовать
Прежде чем вы сможете использовать API-интерфейсы расширений SDK, вам сначала необходимо определить, какие SDK включают API-интерфейсы, которые поддерживают варианты использования вашего приложения.
На справочных страницах API для API расширений SDK указана самая ранняя версия расширения SDK, которую ваше приложение может использовать для доступа к API. Если в документации также указана версия платформы Android (на которую указывает уровень API), то этот API также доступен для всех устройств, работающих под управлением этой версии Android или выше.
Например, ACTION_PICK_IMAGES
обычно доступен в общедоступном SDK, начиная с Android 13 (уровень API 33), но также доступен на устройствах начиная с Android 11 (уровень API 30), если на устройстве установлено как минимум расширение R версии 2. :
Чтобы использовать этот API, вам необходимо скомпилировать SDK с уровнем API не ниже 33 или уровнем расширения не ниже 2.
Чтобы использовать SDK расширения, выполните следующие действия:
- Найдите необходимую минимальную версию расширений, проверив документацию по функциям и справочник по API для API, которые вы хотите использовать.
- Определив необходимую версию расширения для вашего набора функций, откройте диспетчер SDK в Android Studio.
- Выберите запись платформы Android SDK с соответствующей версией расширения (или более высокой версией, поскольку API-интерфейсы являются аддитивными). Например: Android SDK Platform 33, уровень расширения 4.
Объявите эти значения в файле
build.gradle.kts
илиbuild.gradle
вашего приложения:классный
android { compileSdk 33 compileSdkExtension 4 ... }
Котлин
android { compileSdk = 33 compileSdkExtension = 4 ... }
Проверьте, доступны ли расширения SDK
Ваше приложение может проверять, какие версии расширений SDK доступны во время выполнения, а во время разработки вы можете искать версии расширений с помощью команд Android Debug Bridge (adb), как описано в следующих разделах.
Проверка во время выполнения
Ваше приложение может проверить во время выполнения, доступны ли расширения SDK для данной версии платформы, с помощью метода getExtensionVersion()
. Например, следующий код проверит, доступно ли расширение версии 2 или выше для расширения SDK Android 11 (уровень 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; }
Это похоже на проверку на основе Build.VERSION.SDK_INT
:
Котлин
fun isPhotoPickerAvailable(): Boolean { return Build.VERSION.SDK_INT >= 33 }
Ява
public static final boolean isPhotoPickerAvailable() { return Build.VERSION.SDK_INT >= 33; }
Эта проверка SDK_INT
по-прежнему безопасна и действительна, но isPhotoPickerAvailable
будет возвращать false на некоторых устройствах, даже если API расширения доступен. В результате проверка SDK_INT
не является оптимальной, а проверка версии расширения — лучший способ проверить доступность API. Все устройства с SDK_INT
больше или равным 33
(Android 13 или выше) имеют API-интерфейсы Photo Picker в общедоступном SDK, но есть устройства с SDK_INT
меньше 33 (например, Android 11, 12 и 12L), которые также могут получить доступ API, если они имеют версии расширения R не менее 2
.
В этом случае использование проверки версии расширения может помочь вашему приложению предоставить дополнительные функции большему количеству пользователей. См. Имена и константы расширений SDK для получения списка всех констант, которые можно использовать для проверки наличия определенных расширений SDK на устройстве.
Расширения рекламных служб
Как и в случае с общим набором расширений SDK, в справочнике по API AdServices
иногда указывается, что API является частью версии «Расширений рекламных служб». В отличие от обычных расширений SDK, расширения рекламных служб используют константу SdkExtensions.AD_SERVICES
чтобы определить, какая версия установлена на устройстве:
Котлин
fun isAdServicesAvailable(): Boolean { return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4 }
Ява
public static final boolean isAdServicesAvailable() { return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4; }
Дополнительную информацию о функциях расширений рекламных служб и о том, как начать работу, см. в документации по расширениям рекламных служб .
Служебные методы
В некоторых случаях расширения SDK содержат служебные методы Jetpack для проверки доступности API расширений SDK. Например, вы можете использовать функцию библиотеки Jetpack для проверки доступности PhotoPicker , которая абстрагирует условные проверки версий.
Поддержка инструментов
В Android Studio Flamingo | 2022.2.1 или более поздней версии инструмент проверки может сканировать проблемы с версиями расширений SDK в рамках проверки NewAPI. Кроме того, Android Studio может автоматически генерировать правильные проверки версий для API, которые запускаются с помощью расширений SDK.
![](https://developer.android.com/static/images/guide/sdk-extensions/extensions-lint-check.png?authuser=8&hl=ru)
Имена и константы расширений SDK
В следующей таблице описано, как различные наборы расширений SDK, перечисленные в справочной документации API, сопоставляются с константами, которые ваше приложение может использовать для проверки доступности API во время выполнения. Общий набор расширений SDK для каждого общедоступного SDK соответствует значениям Build.VERSION_CODES
.
Имя расширения SDK | Постоянный | Подходящие устройства |
---|---|---|
Расширения R | VERSION_CODES.R | Android 11 (уровень API 30) и выше |
S-расширения | VERSION_CODES.S | Android 12 (уровень API 31) и выше |
Т-расширения | VERSION_CODES.TIRAMISU | Android 13 (уровень API 33) и выше |
Расширения рекламных служб | SdkExtensions.AD_SERVICES | Android 13 (уровень API 33) и выше |
Проверьте с помощью adb
Чтобы проверить, какие расширения SDK доступны на устройстве с помощью adb, выполните следующую команду:
adb shell getprop | grep build.version.extensions
После запуска команды вы увидите вывод, похожий на этот:
[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
В каждой строке показано расширение SDK, присутствующее на устройстве, а также соответствующая версия расширения (в данном случае 3).