Extensiones del SDK

Las extensiones del SDK aprovechan los componentes modulares del sistema para agregar APIs al SDK público para determinados niveles de API publicados. Estas APIs se entregan a los dispositivos cuando los usuarios finales reciben actualizaciones del módulo a través de las actualizaciones del sistema de Google Play. Los desarrolladores pueden usar estas APIs en sus apps para proporcionar funcionalidades adicionales que originalmente no estaban disponibles en el SDK para estas versiones anteriores de Android.

Control de versiones de las APIs

A partir de Android 11 (nivel de API 30), los dispositivos Android incluyen un conjunto de extensiones del SDK. Cuando se agregan nuevas APIs, se incluyen en un nivel de API, pero también se pueden incluir en una extensión del SDK de una versión en particular. Por ejemplo, se agregó la API de ACTION_PICK_IMAGES para el selector de fotos al SDK público en Android 13 (nivel de API 33), pero también está disponible a través de extensiones del SDK a partir de las extensiones R versión 2. Los nombres de extensiones del SDK corresponden a una constante de número entero, ya sea una constante de Build.VERSION_CODES o una definida en la clase SdkExtensions (como SdkExtensions.AD_SERVICES).

Cómo determinar qué extensiones del SDK usar

Para poder usar las APIs de extensiones del SDK, primero debes determinar qué SDKs incluyen las APIs que admiten los casos de uso de tu app.

Las páginas de referencia de la API para las extensiones del SDK especifican la primera versión de extensión del SDK que tu app puede usar para acceder a una API. Si la documentación también especifica una versión de la plataforma de Android (a la que se hace referencia según el nivel de API), esa API también está disponible para todos los dispositivos que ejecutan esa versión de Android o una versión posterior.

Por ejemplo, ACTION_PICK_IMAGES está disponible generalmente en el SDK público a partir de Android 13 (nivel de API 33), pero también está disponible en dispositivos desde Android 11 (nivel de API 30), siempre y cuando el dispositivo tenga extensiones R versión 2, como mínimo:

Para usar esta API, debes compilar con un SDK que tenga, al menos, un nivel de API 33 o un nivel de extensión de 2, como mínimo.

Para usar un SDK de extensión, sigue estos pasos:

1. Para buscar la versión mínima de las extensiones que necesitas, consulta la documentación de funciones y la referencia de la API de las APIs que quieres usar.
2. Después de determinar la versión de extensión requerida para tu conjunto de funciones, abre SDK Manager en Android Studio.
3. Selecciona la entrada de la plataforma del SDK de Android con la versión de extensión correspondiente (o una versión posterior, ya que las APIs son aditivas). Por ejemplo: Plataforma 33 del SDK de Android, nivel de extensión 4.

4. Declara estos valores en el archivo build.gradle.kts o build.gradle de tu app:

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

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

Cómo comprobar si las extensiones del SDK están disponibles

Tu app puede comprobar qué versiones de la extensión del SDK están disponibles en el tiempo de ejecución y, mientras desarrollas, puedes buscar las versiones de las extensiones con los comandos de Android Debug Bridge (adb), como se describe en las siguientes secciones.

Cómo realizar comprobaciones durante el tiempo de ejecución

Durante el tiempo de ejecución, la app puede verificar si las extensiones del SDK están disponibles para una versión determinada de la plataforma mediante el método getExtensionVersion(). Por ejemplo, con el siguiente código, se verificaría si la extensión del SDK versión 2 o una versión superior está disponible para Android 11 (nivel de 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;
}

Esto es similar a hacer una verificación basada en Build.VERSION.SDK_INT:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

Esta verificación de SDK_INT sigue siendo segura y válida, pero isPhotoPickerAvailable se mostrará como falsa en algunos dispositivos, aunque la API de extensión esté disponible. Como resultado, la verificación de SDK_INT no es óptima, y la verificación de versión de la extensión es una mejor manera de comprobar la disponibilidad de la API. Todos los dispositivos con SDK_INT mayores o iguales que 33 (Android 13 o versiones posteriores) tienen las APIs del selector de fotos en el SDK público, pero hay dispositivos con SDK_INT inferior a 33 (como Android 11, 12 y 12L) que también podrían acceder a las APIs si tienen versiones de extensión R de al menos 2.

En este caso, usar una verificación de versión de la extensión puede ayudar a que tu app ofrezca funcionalidad adicional a más usuarios. Consulta nombres y constantes de extensiones del SDK para obtener una lista de todas las constantes que puedes usar para verificar determinadas extensiones del SDK en un dispositivo.

Extensiones de servicios de anuncios

Al igual que el conjunto general de extensiones del SDK, la referencia de la API de AdServices a veces indica que una API forma parte de una versión de "Extensiones de servicios de anuncios". A diferencia de las extensiones generales del SDK, las extensiones de servicios de anuncios usan la constante SdkExtensions.AD_SERVICES para determinar qué versión hay en un dispositivo:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Para obtener más información sobre las funciones de las extensiones de servicios de anuncios y cómo comenzar a usarlas, consulta la documentación sobre las extensiones de servicios de anuncios.

Métodos de utilidad

En algunos casos, las extensiones del SDK tienen métodos de utilidad de Jetpack para verificar la disponibilidad de sus APIs de extensión del SDK. Por ejemplo, puedes usar una función de la biblioteca de Jetpack para verificar la disponibilidad del selector de fotos, lo que abstrae las verificaciones de versión condicionales.

Herramientas de asistencia

En Android Studio Flamingo | 2022.2.1 o versiones posteriores, la herramienta lint puede buscar problemas en las versiones de las extensiones del SDK como parte de su verificación de NewAPI. Además, Android Studio puede generar automáticamente las verificaciones de versión correctas para las APIs que se inician mediante las extensiones del SDK.

Nombres y constantes de las extensiones del SDK

En la siguiente tabla, se describe cómo los diferentes conjuntos de extensiones del SDK que se enumeran en la documentación de referencia de la API se asignan a constantes que tu app puede usar para verificar la disponibilidad de la API durante el tiempo de ejecución. El conjunto general de extensiones del SDK para cada SDK público se asigna a valores de Build.VERSION_CODES.

Cómo verificar con adb

Para comprobar qué extensiones del SDK están disponibles en un dispositivo mediante adb, ejecuta el siguiente comando:

adb shell getprop | grep build.version.extensions

Después de ejecutar el comando, verás un resultado similar al siguiente:

[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

Cada línea muestra una extensión del SDK que está presente en el dispositivo junto con su versión de extensiones correspondiente (en este caso, 3).