Versiones y niveles de API

Hay dos números que describen la misma versión de Android y casi nunca coinciden: el que el usuario ve en los ajustes de su teléfono y el que tú escribes en el fichero de compilación. Uno es marketing y el otro es un contrato. La versión comercial —Android 16, Android 17— sirve para que alguien sepa si su móvil está al día; el nivel de API —36, 37— identifica una superficie de programación concreta, congelada, contra la que puedes compilar con garantías. Esa dualidad ya sería suficiente lío, pero Android le ha añadido en los últimos años dos numeraciones más: los niveles menores, estrenados cuando la plataforma pasó a publicar dos entregas al año, y las extensiones del SDK, que existen porque hoy media plataforma se actualiza por la tienda. Aprender a leer las cuatro es lo que te permitirá entender una tabla de compatibilidad de un vistazo.

Dos numeraciones que no son la misma cosa

Empecemos por la pareja que aparece en cualquier documentación, porque de ella se derivan las otras dos.

La versión comercial cambia una vez al año y es un número redondo, pensado para aparecer en una nota de prensa. El nivel de API es un entero que se incrementa cada vez que la superficie pública de programación cambia de forma significativa, y su valor real está en que es inmutable: el nivel 34 describe para siempre el mismo conjunto de clases, métodos y comportamientos, aunque el teléfono que lo ejecuta reciba parches durante años. Por debajo circula además un nombre en clave interno —los postres siguen existiendo dentro de AOSP aunque Google dejase de anunciarlos— que verás en las constantes del propio SDK.

Esa tabla esconde el cambio más relevante de la última década: el salto de Android 15 a 16 se adelantó al segundo trimestre, y desde entonces hay una entrega mayor a mitad de año y una menor a final. Volveremos sobre el calendario en la última lección del nivel; aquí importa la consecuencia numérica, que es la fila del 36.1.

Consultar la versión en tiempo de ejecución

El acceso canónico es Build.VERSION.SDK_INT, un entero que devuelve el nivel de API del dispositivo. Se compara siempre contra las constantes de Build.VERSION_CODES, nunca contra un número escrito a mano, porque el nombre documenta la intención y sobrevive a la revisión de código.

import android.os.Build
import androidx.annotation.RequiresApi

// Comprobacion clasica: la rama moderna y la de respaldo.
fun tieneApiModerna(): Boolean =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.BAKLAVA

@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun usarApiDeAndroid16() {
    // El compilador y lint ya saben que este cuerpo solo corre en 36 o superior.
}

fun rutaSegura() {
    if (tieneApiModerna()) usarApiDeAndroid16() else respaldo()
}

Hay dos propiedades más en el mismo sitio que casi nadie mira y que resuelven un problema real. Build.VERSION.CODENAME vale la cadena REL en cualquier versión publicada y el nombre en clave cuando el dispositivo ejecuta una preview; Build.VERSION.PREVIEW_SDK_INT vale cero en versiones finales y un número positivo en las de desarrollo. Juntas te permiten distinguir un dispositivo con la beta de la próxima versión de uno con la versión estable, algo indispensable si mandas telemetría y no quieres que un puñado de dispositivos de prueba te contamine las estadísticas de campo.

fun esVersionDePreview(): Boolean =
    Build.VERSION.PREVIEW_SDK_INT > 0 || Build.VERSION.CODENAME != "REL"

Conviene además desactivar una intuición falsa: la secuencia de niveles no es perfectamente paralela a la de versiones comerciales. Ha habido niveles asignados a variantes que nunca fueron una versión de móvil, y ha habido versiones comerciales que cubrieron dos niveles porque una revisión de mantenimiento introdujo APIs. Por eso el mapa entre ambas numeraciones se consulta en una tabla y no se calcula con una fórmula: no la hay.

La anotación RequiresApi no genera comprobación alguna en tiempo de ejecución: es información para el análisis estático, que a cambio te avisa si llamas al método desde un camino sin proteger. La pareja SDK_INT más RequiresApi es el patrón que verás en todo el código de Jetpack, y conviene adoptarlo desde el primer día en lugar de dispersar comparaciones numéricas sueltas.

Niveles menores: el 36.1 que rompió la tradición

Cuando la plataforma pasó a publicar una entrega menor a final de año, apareció un problema aritmético: esa entrega traía APIs nuevas pero no merecía un nivel de API entero. La solución fue estrenar la primera versión fraccionaria de la historia de Android, el 36.1, y con ella una segunda propiedad de consulta que codifica mayor y menor en un solo entero.

import android.os.Build

// SDK_INT sigue devolviendo 36 en una entrega menor de Android 16.
// SDK_INT_FULL distingue 36.0 de 36.1.
fun soportaNovedadesDeLaMenor(): Boolean =
    Build.VERSION.SDK_INT_FULL >= Build.VERSION_CODES_FULL.BAKLAVA_1

La regla mental es sencilla: SDK_INT responde a qué versión mayor de Android es esto, y SDK_INT_FULL responde a qué entrega exacta. Para la inmensa mayoría del código sigue bastando la primera; la segunda solo hace falta cuando dependes de una API que llegó en una entrega menor. Ojo con un detalle práctico: la propiedad completa solo existe a partir de la propia entrega que la introdujo, así que en dispositivos anteriores hay que llegar a ella tras comprobar SDK_INT.

flowchart TD
Q[Necesito una API concreta]
Q --> A[Llego en una version mayor]
Q --> B[Llego en una entrega menor]
Q --> C[Viene de un modulo actualizable]
A --> AR[Comprobar SDK_INT]
B --> BR[Comprobar SDK_INT_FULL]
C --> CR[Comprobar la extension del SDK]
style AR fill:#a6e3a1,color:#11111b
style BR fill:#f9e2af,color:#11111b
style CR fill:#89b4fa,color:#11111b

Extensiones del SDK: la numeración que ignora la versión

Como viste en la lección anterior, buena parte del sistema viaja hoy en módulos que la tienda actualiza por su cuenta. Eso rompe la equivalencia entre versión del sistema y APIs disponibles: un dispositivo antiguo puede tener una API que su nivel de API no contempla, porque llegó dentro de un módulo. Para eso existen las extensiones del SDK, una numeración independiente que se consulta con SdkExtensions.getExtensionVersion.

import android.os.Build
import android.os.ext.SdkExtensions

fun photoPickerDisponible(): Boolean = when {
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU -> true
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.R ->
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    else -> false
}

Leído en voz alta: si el sistema es lo bastante moderno, la API está y punto; si no lo es pero admite extensiones, se pregunta por la versión de extensión concreta. Es la forma más precisa de expresar una dependencia y sustituye a la vieja costumbre de exigir una versión entera del sistema por una sola función.

Las extensiones se numeran por familia y esa familia se identifica con el nivel de API en el que nació el mecanismo, de ahí que en el ejemplo se pregunte por la constante de una versión antigua: no se está preguntando por esa versión del sistema, sino por el contador de extensiones asociado a ella. Es la parte que más confunde al leerlo por primera vez, y se aclara en cuanto asumes que ese argumento es un identificador de familia y no una versión.