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

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

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

1. Найдите необходимую минимальную версию расширений, проверив документацию по функциям и справочник по API для API, которые вы хотите использовать.
2. Определив необходимую версию расширения для вашего набора функций, откройте диспетчер SDK в Android Studio.
3. Выберите запись платформы Android SDK с соответствующей версией расширения (или более высокой версией, поскольку API-интерфейсы являются аддитивными). Например: Android SDK Platform 33, уровень расширения 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-интерфейсы 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.

Имена и константы расширений 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).