API Level: cosa sono, versioni API e targetSdk

Cosa sono gli API Level Android?

API Level Android è un identificatore intero assegnato a ogni versione pubblica dell'API di Android Framework. La prima versione Android 1.0 aveva API Level 1, Android 1.5 — API Level 3, Android 2.2 — API Level 8, Android 4.0 — API Level 14, Android 8.0 — API Level 26, Android 12 — API Level 31, Android 14 — API Level 34, Android 15 — API Level 35, Android 16 (2025) — API Level 36. Ogni nuovo API Level può aggiungere nuove classi, metodi, costanti, permessi e modificare il comportamento di quelli esistenti.

L'API Level non aumenta strettamente di 1 con ogni versione. Ad esempio, Android 4.4W (Wear) ha API 20, mentre Android 5.0 — API 21. I salti sono legati a iterazioni interne e dispositivi Wear OS. Per lo sviluppatore è importante conoscere non il nome della versione (KitKat, Lollipop, Tiramisu), ma il suo API Level — è ciò che viene usato nel codice per i controlli di compatibilità.

Lo scopo principale dell'API Level è la retrocompatibilità. Un'app compilata contro API 34 può funzionare su dispositivi con API 34 e inferiori (se non utilizza nuove API senza controllo). Android Runtime (ART) verifica le chiamate API a livello di sistema e applica le modifiche comportamentali in base al targetSdkVersion dell'app.

Come Android gestisce l'API Level

Durante l'installazione di un'app, PackageManager verifica che l'API Level del dispositivo >= minSdkVersion da AndroidManifest.xml. Se la condizione non è soddisfatta — l'installazione viene bloccata con il messaggio "App not installed". Durante l'esecuzione, Android Runtime monitora le chiamate API che richiedono un API Level superiore e genera NoSuchMethodError o UnsatisfiedLinkError se il metodo non è presente nella versione corrente.

minSdk, targetSdk, compileSdk: differenze e ruolo di ciascun parametro

Nel file build.gradle (Module: app), lo sviluppatore specifica tre parametri di API Level: minSdkVersion, targetSdkVersion e compileSdkVersion. Confonderli è uno degli errori più comuni tra gli sviluppatori Android principianti. Ogni parametro è responsabile di un aspetto diverso della compatibilità, e i loro valori devono essere coerenti.

minSdkVersion

minSdkVersion è l'API Level minimo sul quale l'app può essere installata ed eseguita. I dispositivi con API Level inferiore a minSdk non vedono l'app in Google Play e non possono installarla. Il valore viene scelto in base al pubblico di destinazione: minSdk 21 (Android 5.0) copre il 97% dei dispositivi, minSdk 26 (Android 8.0) — circa l'85%, minSdk 31 (Android 12) — circa il 55% (dati da Android Studio Distribution Dashboard, 2026). Più basso è minSdk, maggiore è la copertura, ma più codice di retrocompatibilità è necessario.

targetSdkVersion

targetSdkVersion è l'API Level contro cui l'app è stata testata. Android usa targetSdk per applicare le modifiche comportamentali: se l'app specifica targetSdk 33, il sistema abilita tutte le modifiche comportamentali introdotte in API 33. Se targetSdk è 31, il sistema non applica le modifiche API 32-33, preservando la compatibilità con il vecchio comportamento. Questo è il parametro più importante per la sicurezza: Google Play richiede targetSdk non più vecchio di 1 anno dall'API Level corrente.

compileSdkVersion

compileSdkVersion è la versione dell'SDK Android contro cui il codice viene compilato. Determina quali API sono disponibili in fase di compilazione. compileSdk deve essere >= targetSdk e, idealmente, uguale all'ultimo API Level stabile. Aumentare compileSdk non influisce sul comportamento in fase di esecuzione — solo sulla disponibilità di nuove API per il compilatore. Dopo aver aumentato compileSdk, è necessario verificare il codice per API obsolete e nuovi requisiti di autorizzazione.

// build.gradle.kts — esempio di configurazione dell'API Level
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

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

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

Nell'esempio di build.gradle.kts, compileSdk = 36 (il più recente al momento della scrittura), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 dà accesso a tutte le API di Android 16. targetSdk 36 abilita tutte le modifiche comportamentali di Android 16. minSdk 26 copre ~85% dei dispositivi. AndroidX Activity KTX e AppCompat forniscono retrocompatibilità per fragment e temi.

AndroidManifest.xml

I parametri minSdk e targetSdk possono anche essere specificati in AndroidManifest.xml, ma i progetti moderni usano build.gradle — i valori di Gradle sovrascrivono il manifest. Nel manifest, può essere utile specificare per librerie e moduli che non utilizzano la configurazione di build di Gradle.

Modifiche comportamentali: come targetSdk influenza il comportamento dell'app

Le modifiche comportamentali sono modifiche al funzionamento del sistema Android che vengono applicate solo alle app con targetSdk >= un determinato API Level. Ogni nuova versione di Android introduce modifiche comportamentali che possono rompere le app esistenti se non vengono aggiornate. Questo è un meccanismo chiave di sicurezza di Android: le app vecchie continuano a funzionare come prima, quelle nuove seguono le regole attuali.

Principali modifiche comportamentali per versione

Android 10 (API 29) — Scoped Storage: le app con targetSdk 29+ non hanno accesso diretto al filesystem condiviso, solo tramite MediaStore, SAF o archiviazione propria. Android 11 (API 30) — Package Visibility: filtro pacchetti, le app vedono solo i pacchetti installati con cui interagiscono. Android 12 (API 31) — Foreground Service Notification: tutti i servizi in primo piano devono mostrare una notifica entro 10 secondi dall'avvio. Android 13 (API 33) — POST_NOTIFICATIONS: autorizzazione in fase di esecuzione per notifiche push. Android 14 (API 34) — Foreground Service Types: dichiarazione obbligatoria del tipo di servizio in primo piano nel manifest.

// Gestione delle modifiche comportamentali di Android 13 (API 33): POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // L'autorizzazione POST_NOTIFICATIONS funziona solo con API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Sotto API 33 l'autorizzazione non è richiesta
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Autorizzazione già concessa, è possibile inviare notifiche
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Mostra spiegazione del perché l'autorizzazione è necessaria
                activity.showRationale()
            }

            else -> {
                // Richiedi autorizzazione
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Crea e mostra notifica
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Notifica")
            .setContentText("Nuovo messaggio")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Registra requestPermissionLauncher in Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Autorizzazione concessa
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Esempio di gestione di POST_NOTIFICATIONS in Kotlin: verificare Build.VERSION.SDK_INT >= TIRAMISU, richiedere l'autorizzazione in fase di esecuzione tramite ActivityResultContracts.RequestPermission, gestire il risultato in un callback. Senza questa autorizzazione, un'app con targetSdk 33+ non può mostrare notifiche push. Sotto API 33 l'autorizzazione non è richiesta — il codice di controllo impedisce la chiamata di API non disponibili.

Scoped Storage (Android 10+)

Scoped Storage è una delle modifiche comportamentali più significative. A partire da API 29 (targetSdk 29+), l'app non può ottenere accesso diretto ai file nelle directory Pictures, Downloads, Music e Documents. Invece, si usa MediaStore per i media, SAF (Storage Access Framework) per file arbitrari e getExternalFilesDir() per l'archiviazione propria. L'eccezione sono le app con autorizzazione MANAGE_EXTERNAL_STORAGE, che richiede l'approvazione di Google Play.

Requisiti di Google Play per API Level e targetSdk

Google Play stabilisce requisiti obbligatori di targetSdkVersion per pubblicare app. Da agosto 2024, Google Play richiede targetSdkVersion >= API 33 (Android 13). Ogni anno la soglia aumenta: le nuove app e gli aggiornamenti devono specificare targetSdk non più vecchio di 1 anno dall'API Level principale corrente. La violazione del requisito porta al blocco della pubblicazione e alla rimozione dell'app dal negozio.

Perché Google Play inasprisce i requisiti

Il motivo principale è la sicurezza. Ogni nuovo API Level Android introduce modifiche comportamentali che chiudono vettori di attacco: Scoped Storage (API 29) previene il furto di file, POST_NOTIFICATIONS (API 33) protegge dalle notifiche spam, Foreground Service Types (API 34) limita i servizi in background nascosti. Le app con targetSdk basso non ricevono queste protezioni e diventano una minaccia per gli utenti. Google Play non può consentire app obsolete su dispositivi moderni.

Verifica della conformità ai requisiti

Google Play Console verifica targetSdkVersion durante il caricamento di APK/AAB. Se targetSdk è inferiore al requisito — la console blocca la pubblicazione con il messaggio: "Your app currently targets API level X and must target at least API level Y". Lo sviluppatore deve aggiornare build.gradle, ricompilare l'app, testare le modifiche comportamentali e ricaricarla. Il formato AAB è raccomandato per tutte le nuove pubblicazioni (obbligatorio da agosto 2021).

Verifica dell'API Level nel codice: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT è una costante intera statica che contiene l'API Level del dispositivo su cui l'app è in esecuzione. È lo strumento principale per i controlli della versione Android in fase di esecuzione. Build.VERSION_CODES contiene costanti nominate per ogni API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Il confronto tramite if (SDK_INT >= VERSION_CODES.TIRAMISU) è il pattern standard.

// Esempi di verifica dell'API Level nel codice Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Verifica di base dell'API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Chiamata API adattativa con verifica
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable è disponibile solo con API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback per dispositivi vecchi
    }

    // 3. Verifica dell'autorizzazione POST_NOTIFICATIONS (solo API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Selezione del provider di immagini per API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ usa PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ usa Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (tutte le versioni)
                "get_content"
            }
        }
    }

    // 5. Verifica in stile Java tramite @TargetApi (per retrocompatibilità)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Il comportamento di Scoped Storage dipende da targetSdk, non da SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informazioni di build per l'analisi
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// Test
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

La classe ApiLevelHelper dimostra tutti i principali pattern di verifica dell'API Level: isAtLeastTiramisu con SDK_INT >= VERSION_CODES, getAdaptiveIcon con fallback per versioni vecchie, getImagePickerProvider con when multi-ramo, getDeviceApiInfo per analisi. La regola chiave è non chiamare nuove API senza verificare SDK_INT, altrimenti l'app si bloccherà con NoSuchMethodError su dispositivi vecchi.

ANT (Android New API) e lint

Android Studio include l'analizzatore statico lint, che avverte sull'uso di API oltre minSdkVersion. Se un metodo viene chiamato senza controllo di SDK_INT, lint lo evidenzia come errore: "Call requires API level 34 (current min is 26)". Soluzioni: aggiungere @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) al metodo o un controllo if di SDK_INT. @TargetApi è un'annotazione obsoleta, si raccomanda @RequiresApi.

Tabella di corrispondenza tra API Level e versioni Android

La tabella degli API Level è uno strumento di riferimento per lo sviluppatore. Conoscendo l'API Level del dispositivo, si può determinare la versione Android e le funzionalità disponibili. La tabella elenca tutte le principali versioni Android da API Level 1 (2008) a API Level 36 (2025). I nomi in codice (Cupcake, Donut, Tiramisu, VanillaIceCream) sono usati internamente da Google e in VERSION_CODES.

Tabella: API Level soglia per le modifiche comportamentali

La tabella seguente mostra gli API Level chiave che introducono modifiche comportamentali che rompono la retrocompatibilità quando si aumenta targetSdk: