compileSdkVersion: conceptos básicos, nuevas API y configuración en Gradle

¿Qué es compileSdkVersion en Android?

compileSdkVersion es un parámetro entero en build.gradle que especifica contra qué versión del SDK de Android compilar el código. Cuando escribes código que usa clases de android.* o androidx.*, el compilador las verifica con las API disponibles en la versión de compileSdk especificada. Si un método se introdujo en la API 36 y compileSdk = 35, el código no se compilará. Si compileSdk = 36, el código se compilará, pero llamar a ese método en un dispositivo con API 35 sin una verificación provocará un error.

compileSdkVersion se carga desde la plataforma Android SDK instalada a través del SDK Manager en Android Studio. Cada nivel de API tiene su propia plataforma: android-21, android-29, android-34, android-35, android-36. La plataforma contiene android.jar — un conjunto de clases, métodos y constantes que utiliza el compilador Kotlin/Java. Si la plataforma no está instalada, Gradle la descargará automáticamente a través de sdkmanager en la primera compilación.

AGP (Android Gradle Plugin) versión 8.7+ recomienda especificar compileSdk como un número entero mediante compileSdk = 36 en Kotlin DSL, sin el prefijo android-. compileSdk también se puede configurar mediante compileSdkVersion 36 en Groovy DSL o compileSdkPreview para versiones preliminares del SDK (developer previews). compileSdkPreview se utiliza para probar niveles de API próximos antes del lanzamiento oficial.

// build.gradle.kts — configuración de compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — último nivel de API estable (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Alternativa: compileSdkPreview para versiones preliminares
// compileSdkPreview = "Baklava"

En el ejemplo, compileSdk = 36 proporciona acceso a todas las API de Android 16 (Baklava). La plataforma Android SDK 36 debe estar instalada en el SDK Manager. compileSdkPreview con el nombre "Baklava" se puede usar para probar API inestables antes del lanzamiento oficial de la plataforma. Después del lanzamiento, la vista previa se reemplaza con compileSdk = 36 estable.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Tres parámetros de nivel de API en build.gradle — compileSdkVersion, targetSdkVersion y minSdkVersion — a menudo se confunden. Cada uno es responsable de un aspecto diferente de la compatibilidad y sus valores deben seguir la regla compileSdk >= targetSdk >= minSdk. minSdk es el límite inferior: los dispositivos por debajo de él no verán la aplicación. targetSdk es el punto de prueba: los cambios de comportamiento se habilitan hasta este nivel. compileSdk es el techo: las API por encima de este nivel no están disponibles para el compilador.

Regla práctica clave: compileSdk se puede aumentar sin necesidad de probar en dispositivos. Esta es una operación segura que simplemente proporciona al compilador una nueva versión de android.jar. El único riesgo son las API obsoletas que pueden eliminarse en la nueva versión de la plataforma, pero esto se detecta en tiempo de compilación y se soluciona fácilmente. Aumentar targetSdk, por otro lado, requiere un ciclo completo de QA.

¿Por qué compileSdk puede ser superior a targetSdk? Imagina que se lanzó Android 16 (API 36) con nuevas API que quieres usar en el código, pero aún no has probado los cambios de comportamiento de la API 36. Estableces compileSdk = 36 (nuevas API disponibles), targetSdk = 35 (cambios de comportamiento de la API 36 desactivados). El código se compilará, usará nuevos métodos bajo comprobaciones SDK_INT y los cambios de comportamiento de la API 36 no romperán la aplicación porque targetSdk = 35.

Ejemplos de combinaciones correctas

compileSdk = 36, targetSdk = 36, minSdk = 26 — compatibilidad total con las últimas API y cambios de comportamiento, cubriendo el 85% de los dispositivos. compileSdk = 36, targetSdk = 34, minSdk = 26 — nuevas API disponibles, cambios de comportamiento solo hasta la API 34. compileSdk = 35, targetSdk = 36 — incorrecto: compileSdk es inferior a targetSdk, la API 36 no está disponible mientras los cambios de comportamiento de la 36 están activos.

Cómo actualizar compileSdkVersion: guía paso a paso

Actualizar compileSdkVersion es una de las operaciones más simples y seguras en un proyecto Android. A diferencia de targetSdk, no requiere pruebas exhaustivas de cambios de comportamiento. Sin embargo, hay algunos pasos que seguir para evitar errores de compilación y advertencias de obsolescencia.

Paso 1 — instala la nueva plataforma a través del SDK Manager en Android Studio: Tools → SDK Manager → SDK Platforms → selecciona el nuevo nivel de API. Si no instalas la plataforma, Gradle intentará descargarla automáticamente, pero esto puede ralentizar la primera compilación. Paso 2 — cambia compileSdk en build.gradle al nuevo valor. Paso 3 — compila (Build → Make Project) y corrige cualquier error de compilación.

Paso 4 — verifica las API obsoletas. Después de actualizar compileSdk, algunos métodos pueden estar marcados como @Deprecated con la nota "removed in API X". Android Studio los resalta con tachado y muestra una advertencia. Reemplaza las llamadas obsoletas con nuevas alternativas. Si la alternativa requiere un nivel de API superior a minSdk, agrega una verificación en tiempo de ejecución. Paso 5 — verifica las dependencias: algunas bibliotecas pueden requerir una versión específica de compileSdk. AGP 8.7+ recomienda compileSdk = 36.

// Después de actualizar compileSdk: reemplazar API obsoletas
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ANTES: método obsoleto (puede eliminarse en la nueva API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Puede quedar obsoleto en API 36
    }

    // DESPUÉS: nueva alternativa (si está disponible)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nueva API de compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Ejemplo de nueva API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

La clase CompileSdkMigration muestra el patrón de migración correcto. El método antiguo memoryClass puede eliminarse en la nueva API — el compilador mostrará un error. La nueva alternativa getMemoryClassSafe solo está disponible en API 36+, por lo que se llama bajo una verificación SDK_INT >= BAKLAVA. Para dispositivos antiguos, se utiliza un fallback con @Suppress("DEPRECATION").

Trabajar con nuevas API: comprobaciones condicionales y fallback

Las nuevas API disponibles gracias a la actualización de compileSdkVersion no se pueden llamar directamente si minSdkVersion es inferior a ese nivel de API. Sin una verificación en tiempo de ejecución, la aplicación fallará con AbstractMethodError, NoSuchMethodError o VerifyError en dispositivos antiguos. El mecanismo de protección principal es verificar Build.VERSION.SDK_INT, llamar a la nueva API solo cuando el nivel de API sea suficiente y proporcionar un fallback para versiones antiguas.

AndroidX proporciona backports para muchas API nuevas, lo que permite usar métodos modernos incluso con un compileSdk bajo. Por ejemplo, la API Activity Result de androidx.activity:activity-ktx:1.9.3 funciona en todas las versiones de Android a partir de la API 14. NotificationCompat de AndroidX permite notificaciones modernas en API antiguas. PhotoPicker está disponible a través de ActivityResultContracts.PickVisualMedia a partir de la API 34+.

// Llamada segura de nueva API con compileSdk 36 y minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: nuevo método para trabajar con color
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nueva API de compileSdk 36 — requiere API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: formato manual para API antiguas
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: no se necesita backport — verificación SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Uso en Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

La clase NewApiHelper demuestra cómo llamar de forma segura a la nueva API Color.toArgbHexString (API 36 hipotética) con formato de fallback para versiones antiguas. El principio clave: compileSdk da acceso a llamar a nuevos métodos en el código, pero una verificación SDK_INT en tiempo de ejecución protege contra fallos en dispositivos antiguos. Sin una verificación SDK_INT, una aplicación con minSdk 26 y compileSdk 36 fallará en Android 8-15.

AGP (Android Gradle Plugin) y compileSdkVersion

Android Gradle Plugin (AGP) es la herramienta de compilación principal para aplicaciones Android. Cada versión de AGP admite un rango específico de compileSdkVersion. AGP 8.7.x (lanzado en 2026) requiere compileSdk >= 34 y recomienda compileSdk = 36. AGP 8.5.x admite compileSdk 33-35. Si compileSdk está por debajo del mínimo para AGP, la compilación fallará con el error: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) también está vinculado a compileSdkVersion. Si tu proyecto usa código nativo en C/C++ a través de NDK, compileSdk determina la versión de los archivos de encabezado y las bibliotecas. NDK r27+ recomienda compileSdk 36. Para bibliotecas con archivos .so, compileSdk afecta el nivel de API mínimo para el código nativo a través de APP_MIN_SDK_VERSION en Application.mk.

Gradle (7.6+) y Kotlin (2.0+) también afectan la compatibilidad con compileSdk. AGP 8.7+ requiere Gradle 8.9+ y Kotlin 2.0+. Al actualizar compileSdk, se recomienda actualizar AGP, Gradle y Kotlin a las últimas versiones estables. Verifica la compatibilidad en la tabla oficial de compatibilidad de Android Gradle Plugin.

Problemas comunes al actualizar compileSdk

Los problemas al actualizar compileSdkVersion se dividen en tres categorías: errores de compilación, advertencias de obsolescencia e incompatibilidades en tiempo de ejecución. Errores de compilación — los métodos se eliminan de la API y el código no se compila. Advertencias de obsolescencia — los métodos están marcados como @Deprecated, el código se compila con advertencias. Incompatibilidades en tiempo de ejecución — las nuevas API son necesarias para cierta funcionalidad y causan errores si el nivel de API en el dispositivo es insuficiente.

El primer problema común — "Cannot resolve symbol X". Esto significa que una clase o método se eliminó de la API pública en la nueva versión del SDK. Solución: encuentra una alternativa en la nueva plataforma o usa un equivalente de AndroidX. Por ejemplo, la clase AsyncTaskLoader quedó obsoleta en la API 28 y se eliminó de la API pública en versiones más recientes. Las alternativas incluyen Kotlin Coroutines o WorkManager.

El segundo problema — cambio de firma de método. En la nueva versión de la API, un método puede haber cambiado el número o tipo de sus parámetros. El compilador Kotlin/Java muestra un error: "None of the following functions can be called with the arguments supplied". Solución: actualiza la llamada al método para que coincida con la nueva firma o agrega una verificación SDK_INT con la llamada a la firma antigua para dispositivos antiguos.

// Resolver problemas al actualizar compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problema: el método hasSystemFeature cambió su firma en API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nueva firma: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Firma antigua: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problema: clase eliminada, use equivalente de AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // En lugar de android.app.FragmentManager (eliminado) use
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

La clase CompileSdkProblemFixer resuelve problemas comunes: la firma cambiada de hasSystemFeature (cambio hipotético en API 36) se maneja mediante una verificación SDK_INT que llama a la versión correcta del método. La clase eliminada android.app.FragmentManager se reemplaza con su equivalente de AndroidX. Para llamadas antiguas donde no existe alternativa, se usa @Suppress("DEPRECATION") con un comentario que explica el motivo de mantenerla.