Расширения SDK

Расширения 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), при условии, что на устройстве установлена ​​как минимум версия 2 расширений R:

Для использования этого API необходимо скомпилировать приложение с SDK, содержащим API уровня не ниже 33 или расширение уровня не ниже 2.

Для использования SDK расширений выполните следующие действия:

1. Минимальную необходимую версию расширений можно узнать, изучив документацию по функциям и справочник API для тех API, которые вы хотите использовать.
2. После определения необходимой версии расширения для вашего набора функций откройте менеджер SDK в Android Studio.
3. Выберите запись «Платформа Android SDK» с соответствующей версией расширения (или более высокой версией, поскольку API суммируются). Например: Android SDK Platform 33, Extension Level 4.

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 выбора фотографий в общедоступном SDK, но есть устройства с SDK_INT меньше 33 (например, Android 11, 12 и 12L), которые также могут получить доступ к API, если у них установлены версии расширения R не ниже 2 .

В этом случае проверка версии расширения может помочь вашему приложению предоставлять дополнительные функции большему числу пользователей. Список всех констант, которые можно использовать для проверки наличия определенных расширений SDK на устройстве, см. в разделе «Имена расширений SDK и константы».

Расширения рекламных сервисов

Подобно общему набору расширений SDK, в справочнике API AdServices иногда указывается, что API является частью версии "Расширений Ad Services". В отличие от общих расширений SDK, расширения Ad Services используют константу 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 и выше инструмент lint может сканировать версии расширений SDK на наличие проблем в рамках проверки NewAPI. Кроме того, Android Studio может автоматически генерировать правильные проверки версий для API, запускаемых с использованием расширений SDK.

Названия расширений SDK и константы

В следующей таблице описано, как различные наборы расширений SDK, перечисленные в справочной документации API, сопоставляются с константами, которые ваше приложение может использовать для проверки доступности API во время выполнения. Общий набор расширений SDK для каждого общедоступного SDK соответствует значениям Build.VERSION_CODES .

Проверьте с помощью 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).