minSdkVersion: qué es y cómo elegir la versión mínima de Android

¿Qué es minSdkVersion en Android?

minSdkVersion es un parámetro entero en build.gradle que especifica el nivel mínimo de API de Android para la instalación de la aplicación. Si el nivel de API del dispositivo está por debajo del valor especificado, PackageManager bloquea la instalación y Google Play Store oculta la aplicación de los resultados de búsqueda para ese dispositivo. minSdkVersion se escribe en AndroidManifest.xml durante la compilación mediante la etiqueta <uses-sdk android:minSdkVersion> y se verifica en cada instalación.

El valor de minSdkVersion es un compromiso entre el alcance de la audiencia y el acceso a nuevas API. Cuanto más bajo sea minSdk, más dispositivos podrán instalar la aplicación, especialmente en regiones en desarrollo donde los smartphones Android antiguos son populares. Cuanto más alto sea minSdk, menos código de compatibilidad hacia atrás se requiere y más API modernas están disponibles sin verificaciones en tiempo de ejecución. Android Jetpack y las bibliotecas AndroidX proporcionan backports de muchas API nuevas a versiones antiguas de Android, lo que permite elegir un minSdk más bajo sin perder funcionalidad.

minSdkVersion afecta todas las etapas del desarrollo: análisis estático (lint usa minSdk para advertencias), compatibilidad de dependencias (las bibliotecas pueden requerir su propio minSdk), pruebas (es necesario probar en dispositivos con minSdk) y Google Play Console (el alcance de la audiencia se calcula según minSdk). Cambiar minSdkVersion es una de las decisiones más importantes en la configuración del proyecto, ya que afecta el código, las pruebas y la base de usuarios.

Dónde se especifica minSdkVersion

Build.gradle.kts (Kotlin DSL) es el estándar moderno en proyectos Android. El parámetro minSdk se define en el bloque defaultConfig a nivel de módulo. El valor puede sobrescribirse para diferentes tipos de compilación y variantes de producto, lo que permite probar en API más bajas sin cambiar el valor principal.

// build.gradle.kts — configuración básica de minSdk
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // Sobrescritura de minSdk para diferentes variantes
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

En el ejemplo, minSdk = 26 corresponde a Android 8.0 Oreo. Este es un valor popular en 2026: solo excluye ~15% de los dispositivos según el Distribution Dashboard de Android Studio. compileSdk = 36 da acceso a todas las API de Android 16, y targetSdk = 36 incluye los cambios de comportamiento de la última versión. Para compilaciones de depuración, minSdk se puede reducir para pruebas en emuladores antiguos.

Cómo elegir minSdkVersion: factores y estrategia

Elegir minSdkVersion es una decisión estratégica basada en el análisis de la audiencia objetivo, los requisitos de API y el ecosistema de bibliotecas. No existe un valor único correcto para todos los proyectos. En 2026, Android Studio recomienda minSdk = 26 (Android 8.0) como nivel base para proyectos nuevos, pero para aplicaciones B2B o soluciones empresariales, pueden ser aceptables valores más bajos o más altos.

Factores para elegir minSdkVersion

El primer factor es el Distribution Dashboard. Android Studio proporciona estadísticas de dispositivos activos por nivel de API basadas en datos de Google Play, actualizadas mensualmente. minSdkVersion debe cubrir al menos el 90-95% de los dispositivos activos del mercado objetivo. Para aplicaciones internacionales con audiencia en África y el Sudeste Asiático, se debe reducir minSdk a 21 (Android 5.0) debido a la alta proporción de dispositivos antiguos.

El segundo factor son los requisitos de dependencias. Cada biblioteca tiene su propio minSdkVersion especificado en su manifiesto. Si una biblioteca requiere minSdk 29 y la aplicación requiere minSdk 26, la compilación fallará con un error de fusión de manifiestos. Las bibliotecas modernas de Google Play Services tienen minSdk 21, Firebase tiene minSdk 21, la mayoría de las bibliotecas Jetpack tienen minSdk 21 o 26, y Compose BOM tiene minSdk 21. Para Compose, el umbral mínimo es API 21.

El tercer factor son las API requeridas. Si una funcionalidad clave de la aplicación requiere una API disponible solo desde un cierto nivel (por ejemplo, PhotoPicker — API 34, Predicted Navigation — API 35), esto puede justificar el aumento de minSdk. Sin embargo, se usa más a menudo una combinación de backports de AndroidX (Activity Result API, NotificationCompat) y verificaciones en tiempo de ejecución para mantener un minSdk bajo.

Estrategia de selección paso a paso

Paso 1: abra Android Studio, File → New Project, y revise el minSdk recomendado en el asistente. Paso 2: verifique el Distribution Dashboard en Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Paso 3: analice las dependencias del proyecto — ejecute la compilación y corrija los conflictos de fusión de manifiestos. Paso 4: evalúe qué API de nivel X se usan realmente sin backports. Paso 5: establezca minSdk como el valor mínimo que cubra el 90%+ de la audiencia objetivo y sea compatible con todas las dependencias.

Cobertura de dispositivos: distribución de niveles de API (2026)

La distribución de dispositivos por nivel de API es una métrica dinámica que cambia cada trimestre. Según el Distribution Dashboard de Android Studio de junio de 2026, aproximadamente el 85% de los dispositivos Android activos funcionan con API 26 (Android 8.0) y superior, el 72% con API 29 (Android 10) y superior, y el 55% con API 31 (Android 12) y superior. El mercado chino tiene sus propias estadísticas debido a la ausencia de Google Play Services en muchos dispositivos Huawei.

Los dispositivos GMS (Google Mobile Services) se actualizan más rápido: la proporción de API 31+ en ellos alcanza el 68% gracias a los requisitos obligatorios de Google Play para los fabricantes. Los dispositivos non-GMS (Huawei, Honor, algunas marcas chinas) tienen una distribución más antigua: la proporción de API 31+ en ellos es de aproximadamente el 35%. Si su aplicación está orientada al mercado internacional, confíe en las estadísticas globales. Si está orientada a China, considere el segmento non-GMS.

Conclusión: para una aplicación internacional, minSdk 26 cubre el 85% de los dispositivos con costos mínimos de compatibilidad hacia atrás. Para aplicaciones con audiencia en regiones en desarrollo, minSdk 21 (97% de cobertura) está justificado pero requerirá más código para trabajar con API heredadas. Para aplicaciones empresariales con un parque de dispositivos controlado, puede establecer minSdk 31 y eliminar completamente el código de respaldo.

Compatibilidad hacia atrás: AndroidX, lint y @RequiresApi

La compatibilidad hacia atrás es el principal desafío con un minSdkVersion bajo. AndroidX (anteriormente Support Library) proporciona backports de API modernas a versiones antiguas de Android: AppCompatActivity para Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat y docenas de otros componentes. Usar equivalentes de AndroidX en lugar de API nativas es el primer paso hacia la compatibilidad.

lint (el analizador estático de Android Studio) escanea el código en busca de llamadas a API por encima de minSdkVersion. Si un método está anotado con @RequiresApi con un nivel de API superior a minSdk y se llama sin verificación, lint resalta un error. Para suprimir la advertencia, use la anotación @SuppressLint("NewApi") en el método o @RequiresApi(Build.VERSION_CODES.TIRAMISU) en toda la función. Las verificaciones en tiempo de ejecución mediante Build.VERSION.SDK_INT son el mecanismo principal para llamar de forma segura a nuevas API en dispositivos antiguos.

// Ejemplo de compatibilidad hacia atrás: PhotoPicker (API 34+) y respaldo
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — funciona en cualquier nivel de API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker solo está disponible desde API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Usando PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Respaldo: GetContent (funciona en todas las versiones)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Este método no se puede llamar en API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

La clase ImagePickerActivity demuestra tres niveles de compatibilidad hacia atrás. Activity Result API de AndroidX funciona en todos los niveles de API, por lo que la selección básica de imágenes no depende de minSdk. PhotoPicker (ACTION_PICK_IMAGES) solo está disponible desde API 34 y se llama bajo una verificación de SDK_INT con un respaldo a GetContent. El método usePhotoPickerOnly está marcado con @RequiresApi — lint no permitirá llamarlo sin verificación. AppCompat de AndroidX adapta automáticamente el tema, los fragmentos y las animaciones a la versión del sistema operativo.

minSdkVersion en bibliotecas y módulos

Las bibliotecas (AAR, JAR) también tienen un minSdkVersion especificado en su manifiesto. Al conectar una biblioteca, Gradle verifica la compatibilidad: si el minSdk de la biblioteca es superior al minSdk de la aplicación, la compilación falla con un error. Para bibliotecas públicas, se recomienda especificar el minSdk más bajo posible (21 para la mayoría de los casos) para no limitar a los consumidores. Si una biblioteca requiere API 29+, pierde ~28% de usuarios potenciales.

Los proyectos multimódulo pueden tener diferentes valores de minSdkVersion para diferentes módulos. Por ejemplo, el módulo :core:network puede tener minSdk 26, mientras que el módulo :feature:camera puede tener minSdk 29 (debido a CameraX con requisitos específicos). Google Play requiere que el minSdk del módulo principal :app sea inferior o igual al minSdk de todos los módulos dependientes. En la práctica, todos los módulos de una misma aplicación suelen tener el mismo minSdk para facilitar el mantenimiento.

// build.gradle.kts — módulo de biblioteca con minSdk bajo
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // Mínimo para máxima cobertura
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, agrega backports
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Un módulo de biblioteca con minSdk = 21 es compatible con el 97% de los dispositivos y no limita a los consumidores. Si la biblioteca usa API superiores a 21, el desarrollador debe agregar verificaciones en tiempo de ejecución o especificar @RequiresApi en los métodos correspondientes. AndroidX Core KTX (minSdk 21) proporciona backports para Context, Bundle, Locale y otras clases del sistema, lo que permite a la biblioteca mantener un minSdk bajo.

Errores comunes al elegir minSdkVersion

Los errores al elegir minSdk pueden costar miles de instalaciones o semanas de desarrollo adicional. El primer error común es copiar minSdk de una plantilla de proyecto sin analizar el Distribution Dashboard. Muchos desarrolladores dejan minSdk = 21 de la plantilla de Android Studio, aunque minSdk 26 sería suficiente para su audiencia y reduciría la cantidad de verificaciones SDK_INT en el código.

El segundo error es un minSdk demasiado alto sin considerar el mercado. Si establece minSdk = 31 (Android 12) para una aplicación internacional, pierde ~45% de los dispositivos. Para una startup o una aplicación de audiencia masiva, esto es un desastre. Siempre verifique el Distribution Dashboard antes de aumentar minSdk y use pruebas A/B en Google Play Console si no está seguro.

El tercer error es ignorar el minSdk de las dependencias. Al agregar una nueva biblioteca, verifique su minSdk en la documentación o en el archivo POM. Firebase ML Kit requiere minSdk 21, algunas bibliotecas de cámara personalizadas requieren minSdk 29. Si la fusión de manifiestos falla en producción debido a una nueva biblioteca, la corrección puede llevar días.

// Ejemplo: verificación de compatibilidad de API en tiempo de ejecución
fun checkFeatureAvailability(): Boolean {
    // Error típico — llamar a una API sin verificar SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — use PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — use MediaStore
            true
        }
        else -> {
            // API < 29 — usamos ACTION_GET_CONTENT
            true
        }
    }
}

La arquitectura correcta para las verificaciones de nivel de API es una expresión when con rangos que cubran todos los valores posibles desde minSdk hasta compileSdk. La regla clave: cualquier llamada a una API de nivel X debe estar protegida por una verificación de VERSION.SDK_INT para todos los dispositivos con nivel de API desde minSdk hasta X. lint ayuda a detectar llamadas no verificadas, pero no puede garantizar una cobertura completa para código dinámico.