targetSdkVersion: Conceptos clave, Behavioural Changes y Google Play

¿Qué es targetSdkVersion en Android?

targetSdkVersion es un parámetro entero en build.gradle que declara el API Level contra el cual se ha probado la aplicación. El sistema Android usa este parámetro para decidir qué behavioural changes aplicar a la aplicación en tiempo de ejecución. Si targetSdkVersion = 33, Android aplica todos los behavioural changes introducidos hasta API 33 inclusive, pero no aplica los cambios de API 34+. Si targetSdkVersion = 34 — se aplican cambios hasta API 34, y así sucesivamente.

La diferencia clave entre targetSdkVersion y minSdkVersion es el mecanismo de acción. minSdk se verifica una vez durante la instalación y bloquea la instalación si no se cumple la condición. targetSdkVersion afecta el comportamiento en tiempo de ejecución del sistema en cada dispositivo, independientemente de la versión de Android en la que se ejecute la aplicación. La misma aplicación con targetSdk 31 se comportará de manera diferente en Android 13, 14 y 15, porque los behavioural changes por encima de 31 están desactivados.

El mecanismo de targetSdkVersion es una herramienta de compatibilidad inversa integrada en Android. Sin él, cada actualización del SO rompería miles de aplicaciones antiguas. Google introdujo este mecanismo en Android 2.1 (API Level 7) y desde entonces lo utiliza como forma estándar de introducir nuevas reglas de seguridad, privacidad y gestión de recursos sin romper las aplicaciones existentes.

// build.gradle.kts — targetSdkVersion en defaultConfig
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

// Verificando targetSdk actual en código
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion contiene el targetSdk de la aplicación
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

En el ejemplo, targetSdk = 36 habilita todos los behavioural changes de Android 16. El código verifica targetSdkVersion mediante context.applicationInfo.targetSdkVersion — esto permite determinar dinámicamente qué modo de compatibilidad está activado. La función auxiliar es útil para bibliotecas que necesitan adaptarse al targetSdk de la aplicación llamante.

Behavioural Changes: cómo targetSdk afecta la aplicación

Behavioural changes son modificaciones en el comportamiento del sistema Android que solo se aplican a aplicaciones con targetSdkVersion >= un determinado API Level. Cada nuevo lanzamiento mayor de Android introduce behavioural changes, y si una aplicación no actualiza targetSdk, estos cambios no entran en vigor. Este mecanismo permite a los desarrolladores actualizar su aplicación a su propio ritmo, en lugar de sincronizadamente con el lanzamiento de un nuevo SO.

Scoped Storage (API 29) es uno de los behavioural changes más significativos. Las aplicaciones con targetSdk 29+ no pueden obtener acceso File directo a los directorios compartidos Pictures, Downloads, Music, Documents. En su lugar, se utiliza MediaStore para multimedia, SAF (Storage Access Framework) para archivos arbitrarios y getExternalFilesDir() para almacenamiento privado. Las aplicaciones antiguas con targetSdk 28 o inferior continúan funcionando con el legado Full Storage Access, pero esto crea un riesgo de seguridad.

POST_NOTIFICATIONS (API 33) es un permiso en tiempo de ejecución para enviar notificaciones. Las aplicaciones con targetSdk 33+ deben solicitar el permiso Manifest.permission.POST_NOTIFICATIONS al usuario mediante el diálogo estándar. Si no se concede el permiso, NotificationManager.silent() no muestra notificaciones al usuario. En Android 13+ sin este permiso, las notificaciones push y las notificaciones locales simplemente no se muestran, lo que puede reducir significativamente la participación del usuario.

Cómo verificar el targetSdk actual

El valor de targetSdkVersion se puede obtener mediante ADB: el comando adb shell dumpsys package com.example.myapp | grep targetSdk muestra targetSdk=34. En código, context.getApplicationInfo().targetSdkVersion devuelve un número entero. Para análisis, es útil registrar targetSdk junto con android.os.Build.VERSION.SDK_INT para entender qué behavioural changes están realmente activos en cada sesión.

Requisitos de Google Play para targetSdkVersion (2026)

Google Play establece requisitos obligatorios de targetSdkVersion para todas las aplicaciones publicadas. Desde agosto de 2024, el targetSdk mínimo = 33 (Android 13). Desde agosto de 2025, targetSdk = 34. Se espera que a partir de agosto de 2026, Google exija targetSdk = 35 (Android 15). Las aplicaciones nuevas y las actualizaciones de las existentes deben cumplir estos requisitos, de lo contrario la consola bloquea la publicación. Esta es una política de Google Play, no una restricción de Android Runtime: una aplicación con targetSdk 34 puede funcionar en Android 16, pero no puede publicarse en Play Store.

Android App Bundle (AAB) es el formato de publicación obligatorio desde agosto de 2021. APK ya no se acepta en Google Play (excepto para aplicaciones de más de 150 MB y algunos proyectos heredados). El formato AAB permite a Google generar APK optimizados para cada API Level y densidad de pantalla, reduciendo el tamaño de descarga entre un 15 y un 30%. Para verificar targetSdk, Google Play analiza el manifiesto AAB y emite un error con el valor mínimo requerido si no cumple.

Google Play Console verifica targetSdkVersion no solo al cargar un nuevo AAB, sino también al actualizar una aplicación existente. Si su aplicación tiene targetSdk 33 y Google eleva el umbral mínimo a 34 — no podrá publicar ninguna actualización hasta que suba targetSdk. Para aplicaciones que no se han actualizado durante mucho tiempo, Google Play puede retirarlas automáticamente de la publicación (unpublish).

Cómo actualizar targetSdkVersion sin errores

Actualizar targetSdkVersion no es solo cambiar un número en build.gradle. Cada behavioural change puede romper la funcionalidad existente si el código no se prepara con anticipación. Se recomienda comenzar la preparación 3-6 meses antes de la fecha límite de Google Play, especialmente si la aplicación es grande y utiliza muchas API del sistema.

Proceso paso a paso: Paso 1 — estudie los behavioural changes para el nuevo API Level en la documentación de Android Developers (página "Behavioural Changes by API Level"). Paso 2 — cree una rama targetSdk-update y cambie targetSdk al nuevo valor. Paso 3 — ejecute la aplicación en un emulador o dispositivo con el nuevo API Level y verifique cada funcionalidad relacionada con los cambios. Paso 4 — corrija errores: agregue permisos, cambie el manejo de archivos, actualice el manifiesto.

Paso 5 — pruebe en dispositivos antiguos. Elevar targetSdk no afecta a los dispositivos con API Level inferior al nuevo targetSdk, pero los behavioural changes se aplican a todos los dispositivos con API Level >= targetSdk. Si elevó targetSdk de 33 a 34, en dispositivos con API 34+ se activarán los behavioural changes de API 34. En dispositivos con API 33 nada cambiará.

// Preparación para targetSdk 35: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox restringe Advertising ID desde API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identificador no disponible, use MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Verificación: qué behavioural changes están activos
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

La clase AdsManager muestra la preparación para Privacy Sandbox (API 35). Advertising ID deja de estar disponible a partir de API 35 con targetSdk 35+. La función getActiveChanges demuestra el patrón correcto para verificar behavioural changes: es necesario verificar tanto SDK_INT del dispositivo como targetSdk de la aplicación. Solo cuando ambas condiciones coinciden, el cambio está realmente activo.

Android 15 (API 35): behavioural changes clave

Android 15 (API 35, Vanilla Ice Cream) introduce varios behavioural changes críticos que los desarrolladores deben considerar al actualizar targetSdk a 35. Primero — Privacy Sandbox for Android. Esta es la iniciativa de Google para reemplazar Advertising ID con API más privadas: Topics API (intereses del usuario), Protected Audience (remarketing) y Attribution Reporting (conversiones). A partir de API 35, Advertising ID deja de ser un identificador estable y puede devolver un valor nulo.

El segundo cambio — Foreground Service Types (API 34, continuado en API 35). A partir de API 34, cada aplicación con targetSdk 34+ debe especificar el tipo de servicio en primer plano en el manifiesto: dataSync, systemExempted, shortService, location, mediaPlayback y otros. Sin esto, el sistema genera ForegroundServiceTypeNotAllowedException. En API 35 se ha agregado un nuevo tipo health y se ha endurecido la validación de los tipos existentes. Todos los servicios en primer plano deben ser revisados.

El tercer cambio — restricción en SCHEDULE_EXACT_ALARM. A partir de API 35, las aplicaciones con targetSdk 35+ no pueden usar SCHEDULE_EXACT_ALARM sin permiso explícito del usuario. El sistema muestra un diálogo y el usuario debe aprobar la programación exacta. Para alarmas y temporizadores, esto significa un paso adicional en UX. Una alternativa es usar alarmas inexactas con un margen de 10 minutos.

// Android 15 (API 35): verificación de SCHEDULE_EXACT_ALARM
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: se requiere permiso del usuario
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Por debajo de API 35 — alarmas exactas disponibles sin permiso
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox y la restricción de alarmas son los dos behavioural changes más críticos de API 35. Los SDK de anuncios deberán migrar a Topics API y Attribution Reporting. Para aplicaciones con alarmas y recordatorios — adaptación de UX para el diálogo de permiso. Ignorar estos cambios provocará fallos en la aplicación en tiempo de ejecución en Android 15 o una monetización publicitaria rota.

Diferencia entre targetSdk y compileSdk

La diferencia entre targetSdkVersion y compileSdkVersion es una de las fuentes más comunes de confusión entre los desarrolladores de Android. compileSdkVersion es la versión del SDK contra la que se compila el código. Determina qué API están disponibles en tiempo de compilación, pero no afecta el comportamiento en tiempo de ejecución. targetSdkVersion es la versión contra la que se prueba la aplicación — determina qué behavioural changes se aplican en tiempo de ejecución. compileSdk puede y debe ser mayor o igual que targetSdk.

La regla es simple: compileSdk >= targetSdk >= minSdk. compileSdk normalmente es igual al último API Level estable (en 2026 — 36). targetSdk debe ser lo más alto posible entre las versiones que haya probado. minSdk debe ser lo más bajo posible para maximizar la cobertura. Elevar compileSdk no requiere probar behavioural changes — solo abre acceso a nuevas API para el compilador. Elevar targetSdk requiere un ciclo completo de pruebas de todos los behavioural changes.

En la práctica: si desea usar una nueva API de Android 16 (API 36) pero aún no ha probado los behavioural changes de API 36, establezca compileSdk = 36, targetSdk = 35. El código se compilará con las nuevas API, pero los behavioural changes de API 36 no se aplicarán. Una vez que haya probado todos los cambios — eleve targetSdk a 36.