minSdkVersion: cos'è e come scegliere la versione minima di Android

Cos'è minSdkVersion in Android?

minSdkVersion è un parametro intero in build.gradle che specifica il livello API Android minimo per l'installazione dell'app. Se il livello API del dispositivo è inferiore al valore specificato, PackageManager blocca l'installazione e Google Play Store nasconde l'app dai risultati di ricerca per quel dispositivo. minSdkVersion viene scritto in AndroidManifest.xml durante la compilazione tramite il tag <uses-sdk android:minSdkVersion> e viene verificato a ogni installazione.

Il valore di minSdkVersion è un compromesso tra la portata del pubblico e l'accesso alle nuove API. Più basso è minSdk, più dispositivi possono installare l'app, specialmente nelle regioni in via di sviluppo dove gli smartphone Android più vecchi sono popolari. Più alto è minSdk, meno codice di retrocompatibilità è richiesto e più API moderne sono disponibili senza controlli a runtime. Android Jetpack e le librerie AndroidX forniscono backport di molte nuove API alle versioni precedenti di Android, consentendo di scegliere un minSdk più basso senza perdere funzionalità.

minSdkVersion influisce su tutte le fasi dello sviluppo: analisi statica (lint usa minSdk per gli avvisi), compatibilità delle dipendenze (le librerie possono richiedere il proprio minSdk), test (è necessario testare su dispositivi con minSdk) e Google Play Console (la portata del pubblico viene calcolata in base a minSdk). Modificare minSdkVersion è una delle decisioni più importanti nella configurazione del progetto, poiché influisce su codice, test e base utenti.

Dove viene specificato minSdkVersion

Build.gradle.kts (Kotlin DSL) è lo standard moderno nei progetti Android. Il parametro minSdk viene impostato nel blocco defaultConfig a livello di modulo. Il valore può essere sovrascritto per diversi tipi di build e varianti di prodotto, consentendo di testare su API inferiori senza modificare il valore principale.

// build.gradle.kts — configurazione di base di 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"
    }

    // Override di minSdk per diverse varianti
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

Nell'esempio, minSdk = 26 corrisponde ad Android 8.0 Oreo. Questo è un valore popolare nel 2026: esclude solo ~15% dei dispositivi secondo il Distribution Dashboard di Android Studio. compileSdk = 36 dà accesso a tutte le API di Android 16, e targetSdk = 36 include le modifiche comportamentali dell'ultima versione. Per le build di debug, minSdk può essere abbassato per i test su emulatori più vecchi.

Come scegliere minSdkVersion: fattori e strategia

Scegliere minSdkVersion è una decisione strategica basata sull'analisi del pubblico di destinazione, dei requisiti API e dell'ecosistema delle librerie. Non esiste un singolo valore corretto per tutti i progetti. Nel 2026, Android Studio raccomanda minSdk = 26 (Android 8.0) come livello base per i nuovi progetti, ma per applicazioni B2B o soluzioni aziendali, valori inferiori o superiori possono essere accettabili.

Fattori per scegliere minSdkVersion

Il primo fattore è il Distribution Dashboard. Android Studio fornisce statistiche dei dispositivi attivi per livello API basate sui dati di Google Play, aggiornate mensilmente. minSdkVersion dovrebbe coprire almeno il 90-95% dei dispositivi attivi del mercato di destinazione. Per le app internazionali con pubblico in Africa e Sud-Est asiatico, minSdk dovrebbe essere abbassato a 21 (Android 5.0) a causa dell'elevata percentuale di dispositivi più vecchi.

Il secondo fattore sono i requisiti delle dipendenze. Ogni libreria ha il proprio minSdkVersion specificato nel suo manifest. Se una libreria richiede minSdk 29 e l'app richiede minSdk 26, la build fallirà con un errore di fusione del manifest. Le librerie moderne di Google Play Services hanno minSdk 21, Firebase ha minSdk 21, la maggior parte delle librerie Jetpack ha minSdk 21 o 26, e Compose BOM ha minSdk 21. Per Compose, la soglia minima è API 21.

Il terzo fattore sono le API richieste. Se una funzionalità chiave dell'app richiede un'API disponibile solo da un certo livello (ad esempio, PhotoPicker — API 34, Predicted Navigation — API 35), questo può giustificare l'aumento di minSdk. Tuttavia, una combinazione di backport AndroidX (Activity Result API, NotificationCompat) e controlli a runtime è più spesso utilizzata per mantenere un minSdk basso.

Strategia di selezione passo passo

Passo 1: apri Android Studio, File → New Project, e controlla il minSdk raccomandato nella procedura guidata. Passo 2: controlla il Distribution Dashboard in Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Passo 3: analizza le dipendenze del progetto — esegui la build e correggi i conflitti di fusione del manifest. Passo 4: valuta quali API di livello X sono effettivamente utilizzate senza backport. Passo 5: imposta minSdk come valore minimo che copre il 90%+ del pubblico di destinazione ed è compatibile con tutte le dipendenze.

Copertura dei dispositivi: distribuzione dei livelli API (2026)

La distribuzione dei dispositivi per livello API è una metrica dinamica che cambia ogni trimestre. Secondo il Distribution Dashboard di Android Studio di giugno 2026, circa l'85% dei dispositivi Android attivi funziona su API 26 (Android 8.0) e superiore, il 72% su API 29 (Android 10) e superiore, e il 55% su API 31 (Android 12) e superiore. Il mercato cinese ha le proprie statistiche a causa dell'assenza di Google Play Services su molti dispositivi Huawei.

I dispositivi GMS (Google Mobile Services) si aggiornano più velocemente: la quota di API 31+ su di essi raggiunge il 68% grazie ai requisiti obbligatori di Google Play per i produttori. I dispositivi non GMS (Huawei, Honor, alcuni marchi cinesi) hanno una distribuzione più vecchia: la quota di API 31+ su di essi è di circa il 35%. Se la tua app è rivolta al mercato internazionale, affidati alle statistiche globali. Se è rivolta alla Cina, considera il segmento non GMS.

Conclusione: per un'app internazionale, minSdk 26 copre l'85% dei dispositivi con costi minimi di retrocompatibilità. Per le app con pubblico nelle regioni in via di sviluppo, minSdk 21 (97% di copertura) è giustificato ma richiederà più codice per funzionare con API legacy. Per le app aziendali con un parco dispositivi controllato, puoi impostare minSdk 31 ed eliminare completamente il codice di fallback.

Retrocompatibilità: AndroidX, lint e @RequiresApi

La retrocompatibilità è la sfida principale con un minSdkVersion basso. AndroidX (precedentemente Support Library) fornisce backport di API moderne alle versioni precedenti di Android: AppCompatActivity per Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat e decine di altri componenti. Usare equivalenti AndroidX invece delle API native è il primo passo verso la compatibilità.

lint (l'analizzatore statico di Android Studio) scansiona il codice alla ricerca di chiamate API superiori a minSdkVersion. Se un metodo è annotato con @RequiresApi a un livello API superiore a minSdk e viene chiamato senza controllo, lint evidenzia un errore. Per sopprimere l'avviso, usa l'annotazione @SuppressLint("NewApi") sul metodo o @RequiresApi(Build.VERSION_CODES.TIRAMISU) sull'intera funzione. I controlli a runtime tramite Build.VERSION.SDK_INT sono il meccanismo principale per chiamare in sicurezza nuove API su dispositivi più vecchi.

// Esempio di retrocompatibilità: PhotoPicker (API 34+) e fallback
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) — funziona a qualsiasi livello API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker è disponibile solo da API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Utilizzo di PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (funziona su tutte le versioni)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Questo metodo non può essere chiamato su API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

La classe ImagePickerActivity dimostra tre livelli di retrocompatibilità. Activity Result API di AndroidX funziona a tutti i livelli API, quindi la selezione di base dell'immagine non dipende da minSdk. PhotoPicker (ACTION_PICK_IMAGES) è disponibile solo da API 34 e viene chiamato sotto un controllo SDK_INT con fallback a GetContent. Il metodo usePhotoPickerOnly è marcato con @RequiresApi — lint non ne consentirà la chiamata senza controllo. AppCompat di AndroidX adatta automaticamente il tema, i fragment e le animazioni alla versione del sistema operativo.

minSdkVersion in librerie e moduli

Le librerie (AAR, JAR) hanno anch'esse un minSdkVersion specificato nel loro manifest. Quando si collega una libreria, Gradle verifica la compatibilità: se il minSdk della libreria è superiore al minSdk dell'app, la build fallisce con un errore. Per le librerie pubbliche, si raccomanda di specificare il minSdk più basso possibile (21 per la maggior parte dei casi) per non limitare i consumatori. Se una libreria richiede API 29+, perde ~28% di utenti potenziali.

I progetti multi-modulo possono avere diversi valori di minSdkVersion per diversi moduli. Ad esempio, il modulo :core:network può avere minSdk 26, mentre il modulo :feature:camera può avere minSdk 29 (a causa di CameraX con requisiti specifici). Google Play richiede che il minSdk del modulo principale :app sia inferiore o uguale al minSdk di tutti i moduli dipendenti. In pratica, tutti i moduli di una stessa app hanno solitamente lo stesso minSdk per semplificare la manutenzione.

// build.gradle.kts — modulo libreria con minSdk basso
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Minimo per la massima copertura
        targetSdk = 36
    }
}

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

Un modulo libreria con minSdk = 21 è compatibile con il 97% dei dispositivi e non limita i consumatori. Se la libreria utilizza API superiori a 21, lo sviluppatore deve aggiungere controlli a runtime o specificare @RequiresApi sui metodi pertinenti. AndroidX Core KTX (minSdk 21) fornisce backport per Context, Bundle, Locale e altre classi di sistema, consentendo alla libreria di mantenere un minSdk basso.

Errori comuni nella scelta di minSdkVersion

Gli errori nella scelta di minSdk possono costare migliaia di installazioni o settimane di sviluppo aggiuntivo. Il primo errore comune è copiare minSdk da un modello di progetto senza analizzare il Distribution Dashboard. Molti sviluppatori lasciano minSdk = 21 dal modello di Android Studio, anche se minSdk 26 sarebbe sufficiente per il loro pubblico e ridurrebbe il numero di controlli SDK_INT nel codice.

Il secondo errore è un minSdk troppo alto senza considerare il mercato. Se imposti minSdk = 31 (Android 12) per un'app internazionale, perdi ~45% dei dispositivi. Per una startup o un'app di massa, questo è un disastro. Controlla sempre il Distribution Dashboard prima di aumentare minSdk e usa i test A/B in Google Play Console se non sei sicuro.

Il terzo errore è ignorare il minSdk delle dipendenze. Quando aggiungi una nuova libreria, controlla il suo minSdk nella documentazione o nel file POM. Firebase ML Kit richiede minSdk 21, alcune librerie fotocamera personalizzate richiedono minSdk 29. Se la fusione del manifest fallisce in produzione a causa di una nuova libreria, la correzione può richiedere giorni.

// Esempio: controllo di compatibilità API a runtime
fun checkFeatureAvailability(): Boolean {
    // Errore tipico — chiamare un'API senza controllare SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — usa PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — usa MediaStore
            true
        }
        else -> {
            // API < 29 — usiamo ACTION_GET_CONTENT
            true
        }
    }
}

L'architettura corretta per i controlli di livello API è un'espressione when con intervalli che coprono tutti i possibili valori da minSdk a compileSdk. La regola chiave: qualsiasi chiamata a un'API di livello X deve essere protetta da un controllo VERSION.SDK_INT per tutti i dispositivi con livello API da minSdk a X. lint aiuta a rilevare le chiamate non controllate, ma non può garantire una copertura completa per il codice dinamico.