Расширения 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 расширений 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, которые вы хотите использовать.
2. Определив, какая версия расширения вам нужна, откройте SDK Manager в Android Studio.
3. Выберите запись Android SDK Platform с соответствующей версией расширения (или более поздней, поскольку API являются аддитивными). Пример: Android SDK Platform 33, Extension Level 4.

4. Объявите эти значения в файле build.gradle.kts или build.gradle своего приложения:

   Яркий

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }

   Kotlin

   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 является частью версии расширений рекламных сервисов. В отличие от общих расширений 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 Extensions есть служебные методы Jetpack для проверки доступности API SDK Extensions. Например, вы можете использовать функцию библиотеки Jetpack, чтобы проверить доступность PhotoPicker. Это позволит не использовать условные проверки версий.

Поддержка инструментов

В Android Studio Flamingo 2022.2.1 и более поздних версиях инструмент lint может сканировать проблемы с версиями SDK Extension в рамках проверки 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).