SDK Platform: cos'è, versioni e Android SDK Manager

Cos'è SDK Platform

SDK Platform è un componente fondamentale di Android SDK, che rappresenta un set completo di librerie e strumenti per sviluppare applicazioni per una versione specifica di Android. Ogni piattaforma è identificata dal proprio API Level — un numero intero che aumenta con le nuove versioni del SO. Ad esempio, Android 13 corrisponde all'API Level 33, Android 14 all'API Level 34, Android 15 all'API Level 35.

A differenza di Android Studio (IDE), SDK Platform non contiene editor di codice o debugger. È un layer di sistema che si collega al compilatore e al sistema di build. Quando uno sviluppatore scrive import android.app.Activity, il compilatore prende questa classe da android.jar di uno specifico SDK Platform. Senza una piattaforma installata con l'API Level richiesto, il codice non verrà compilato.

Google rilascia un nuovo SDK Platform per ogni versione stabile di Android. La storia include più di 35 API Level — da Android 1.0 (API 1) ad Android 15 (API 35). Ogni piattaforma è retrocompatibile: il codice scritto per API Level 21 funzionerà su API Level 35, ma non viceversa.

Perché è necessario un SDK Platform separato per ogni versione

Android si evolve rapidamente: ogni versione aggiunge nuove API, modifica il comportamento delle esistenti e introduce restrizioni. Ad esempio, Android 10 (API 29) ha introdotto Scoped Storage, Android 12 (API 31) — SplashScreen API, Android 14 (API 34) — flag obbligatori di BroadcastReceiver. Lo sviluppatore deve compilare l'applicazione contro la piattaforma attuale per utilizzare queste funzionalità.

Allo stesso tempo, l'applicazione può funzionare su versioni precedenti del SO. Per questo, in Gradle viene specificato minSdk — l'API Level minimo su cui l'applicazione viene eseguita. Il codice utilizza controlli di versione e chiamate API condizionali. Questo approccio garantisce compatibilità senza perdere nuove funzionalità.

Composizione di SDK Platform: componenti principali

SDK Platform non è un singolo file, ma un insieme di componenti che insieme garantiscono la compilazione, la costruzione e il test dell'applicazione. L'elemento principale è android.jar — un archivio con le classi delle API Android incluse in questa versione. Questo file si collega al compilatore Kotlin o Java e determina quali classi, metodi e annotazioni sono disponibili per lo sviluppatore.

Immagini di sistema ed emulatore

Ogni SDK Platform include una System Image — un'immagine del sistema operativo per l'emulatore Android Virtual Device. Senza l'immagine corrispondente, l'emulatore non può avviare un dispositivo virtuale con l'API Level richiesto. Le System Images sono di diversi tipi: Google APIs (con servizi Google), Google Play (con Play Store) e AOSP (Android puro senza servizi Google).

Strumenti di compilazione e debug

SDK Platform include una versione di Build-Tools e Platform-Tools ottimizzata per questo API Level. Build-Tools contiene aapt2 (Android Asset Packaging Tool), dx/d8 (compilatore Dalvik/ART) e ApkSigner. Platform-Tools fornisce ADB (Android Debug Bridge), fastboot e SQLite. Questi strumenti vengono aggiornati indipendentemente da SDK Platform tramite SDK Manager.

Risorse della piattaforma

Ogni piattaforma include risorse standard di Android — temi di sistema, stili, animazioni, colori e dimensioni. Queste risorse vengono utilizzate durante la compilazione: se uno sviluppatore fa riferimento a @android:style/Theme.Material.Light, il sistema di build prende la definizione dalle risorse di SDK Platform. Questo garantisce un aspetto uniforme dei componenti di sistema su tutti i dispositivi.

API Level e versioni di SDK Platform

API Level è un identificatore intero della versione di Android SDK. Ogni versione di Android corrisponde a un API Level che aumenta monotonicamente. Lo sviluppatore specifica l'API Level in tre parametri chiave di build.gradle: compileSdk, minSdk e targetSdk. La scelta di questi parametri determina quali API sono disponibili e come il sistema gestisce l'applicazione.

Google raccomanda di mantenere minSdk a un livello non inferiore alla soglia di distribuzione corrente — secondo Android Studio Distribution Dashboard (2026), circa il 95% dei dispositivi esegue Android 8.0 (API 26) e superiore. compileSdk dovrebbe essere l'ultimo stabile — questo dà accesso a nuove API e permette ai controlli lint di rilevare metodi obsoleti.

Evoluzione dell'API Level: cambiamenti chiave

Con ogni nuovo API Level, Google introduce cambiamenti significativi. Android 6.0 (API 23) ha aggiunto le autorizzazioni runtime — l'applicazione richiede autorizzazioni durante l'esecuzione, non all'installazione. Android 8.0 (API 26) ha introdotto la compilazione automatica dei moduli e i canali di notifica. Android 12 (API 31) ha cambiato radicalmente l'approccio agli intent — è apparsa SplashScreen API e l'esportazione di componenti tramite l'attributo exported. Android 14 (API 34) ha reso obbligatorio specificare flag per BroadcastReceiver e ha introdotto restrizioni severe sui servizi in primo piano.

Comprendere la storia degli API Level aiuta lo sviluppatore a scegliere la giusta strategia di compatibilità. Se l'applicazione usa compileSdk 35 ma minSdk 26, il codice può chiamare metodi dell'API 35 solo dopo aver verificato la versione tramite Build.VERSION.SDK_INT. Questo approccio è chiamato sviluppo a versione controllata ed è uno standard di settore.

SDK Manager: installazione e configurazione

SDK Manager è uno strumento per gestire i componenti di Android SDK: installare nuovi SDK Platform, aggiornare quelli esistenti e rimuovere quelli obsoleti. SDK Manager è disponibile come interfaccia grafica in Android Studio e anche come strumento a riga di comando tramite sdkmanager. La riga di comando di SDK Manager è comoda da usare in pipeline CI/CD dove non è presente un'interfaccia grafica.

SDK Manager installa le piattaforme nella directory Android SDK, che per impostazione predefinita si trova in $HOME/Android/Sdk su Linux e macOS o %LOCALAPPDATA%\Android\Sdk su Windows. All'interno della directory platforms ci sono cartelle chiamate android-{API Level}, ciascuna contenente la SDK Platform completa.

Installazione di SDK Platform tramite sdkmanager

Il comando sdkmanager accetta un identificatore di pacchetto nel formato "platforms;android-{API}". Ad esempio, per installare SDK Platform 35 il comando è:

# Installare SDK Platform per API Level 35
sdkmanager "platforms;android-35"

# Installare più piattaforme con un comando
sdkmanager "platforms;android-34" "platforms;android-33" "platforms;android-31"

# Elencare le piattaforme installate
sdkmanager --list_installed | grep platforms

# Rimuovere la piattaforma obsoleta
sdkmanager --uninstall "platforms;android-28"

Installazione automatica tramite Gradle

I progetti Android moderni usano Gradle Plugin, che può installare automaticamente SDK Platform al primo build. Per farlo, è necessario specificare compileSdk in build.gradle e aggiungere la directory SDK nella configurazione locale. Android Studio offre anche di installare la piattaforma mancante all'apertura di un progetto — basta cliccare sul pulsante "Install SDK Platform" nella finestra di sincronizzazione Gradle.

È importante aggiornare regolarmente SDK Platform tramite SDK Manager — insieme alla piattaforma vengono aggiornati Build-Tools e Platform-Tools, che influenzano le prestazioni di compilazione e la stabilità del debug. Google raccomanda di verificare gli aggiornamenti SDK ogni 2–3 settimane, specialmente prima di pubblicare una nuova versione dell'applicazione su Google Play.

Configurazione di un'immagine di sistema per l'emulatore

Per eseguire l'emulatore con uno specifico API Level, è necessario installare una System Image della stessa versione. SDK Manager permette di scaricare immagini di diverse architetture (x86_64, arm64-v8a) e tipi (Google APIs, Google Play, AOSP). Dopo aver scaricato l'immagine, AVD Manager crea un dispositivo virtuale basato su di essa.

# Installare System Image con Google APIs per API 35
sdkmanager "system-images;android-35;google_apis;x86_64"

# Creare AVD tramite riga di comando
avdmanager create avd -n pixel8 -k "system-images;android-35;google_apis;x86_64"

# Elencare AVD creati
avdmanager list avd

compileSdk, targetSdk e minSdk in Gradle

Tre parametri in build.gradle definiscono come l'applicazione funziona con SDK Platform. compileSdk è l'API Level utilizzato per la compilazione. Questo parametro specifica quali classi delle API Android sono disponibili nel codice. compileSdk dovrebbe essere il più recente dei tre e non influisce sul comportamento runtime — l'applicazione viene compilata ma utilizza solo le API disponibili sul dispositivo.

minSdk è l'API Level minimo su cui l'applicazione può essere installata. Google Play non permetterà di installare l'applicazione su un dispositivo con versione inferiore a minSdk. Questo parametro definisce la soglia di compatibilità e influisce sulla copertura del pubblico. Più basso è minSdk, più dispositivi sono supportati, ma meno nuove API possono essere utilizzate senza controlli.

targetSdk è l'API Level contro cui l'applicazione è stata testata. Il sistema Android usa targetSdk per applicare cambiamenti comportamentali: se l'applicazione non viene aggiornata a un nuovo API Level, il sistema attiva la modalità di compatibilità per le versioni precedenti. Google Play richiede che targetSdk non sia inferiore a un certo livello — nel 2026 è API 34 (Android 14).

Esempio di configurazione Gradle

android {
    compileSdk 35

    defaultConfig {
        applicationId "com.example.app"
        minSdk 26
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

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

// La versione di Android SDK deve essere installata tramite SDK Manager
// sdkmanager "platforms;android-35"

Come scegliere compileSdk, minSdk e targetSdk

La strategia di selezione dipende dagli obiettivi del progetto. Per una nuova applicazione: compileSdk — l'ultimo stabile (35 all'inizio del 2026), minSdk — API 26 (Android 8.0, copre il 95% dei dispositivi), targetSdk — l'ultimo stabile. Per aggiornare un'applicazione esistente: aumentare compileSdk immediatamente, targetSdk — dopo aver testato tutti i cambiamenti comportamentali, minSdk — solo quando è necessario abbandonare i dispositivi obsoleti.

Google richiede che targetSdk venga aggiornato entro un anno dal rilascio di una nuova versione di Android. Le applicazioni che non soddisfano questo requisito non possono pubblicare aggiornamenti su Google Play. Per tenere traccia delle scadenze, utilizzare il calendario ufficiale degli aggiornamenti di Android OS.

Esempi di lavoro con SDK Platform nel codice

Quando si sviluppa per diverse versioni di Android, è necessario considerare la disponibilità delle API. Se l'applicazione usa compileSdk 35 ma funziona su un dispositivo con API 31, chiamare metodi aggiunti nell'API 34 causerà NoSuchMethodError o AbstractMethodError. Per chiamare in sicurezza le nuove API, vengono utilizzati controlli di versione tramite Build.VERSION.SDK_INT.

Verifica dell'API Level in runtime

class FeatureChecker {
    fun registerNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            // I canali di notifica sono disponibili dall'API 26
            val channel = NotificationChannel(
                "updates",
                "Aggiornamenti",
                NotificationManager.IMPORTANCE_DEFAULT
            )
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

Utilizzo di nuove API con @RequiresApi

Per i metodi che vengono chiamati solo su versioni specifiche, utilizzare l'annotazione @RequiresApi. Questo indica ai controlli lint che il metodo è sicuro e disabilita gli avvisi. Combinata con il controllo di SDK_INT, l'annotazione rende il codice più pulito e comprensibile per i revisori.

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun scheduleExactAlarm(manager: AlarmManager, time: Long) {
    // API 34: scheduleExact con flag SCHEDULE_EXACT_ALARM
    if (manager.canScheduleExactAlarms()) {
        manager.setExact(AlarmManager.RTC_WAKEUP, time, pendingIntent)
    } else {
        // Richiedere autorizzazione SCHEDULE_EXACT_ALARM
        val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
        context.startActivity(intent)
    }
}

fun safeScheduleAlarm(context: Context, triggerTime: Long) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleExactAlarm(getAlarmManager(context), triggerTime)
    } else {
        // Vecchio metodo setExact senza controllo autorizzazioni
        getAlarmManager(context).setExact(AlarmManager.RTC_WAKEUP, triggerTime, pendingIntent)
    }
}

Determinazione della SDK Platform installata

A volte è necessario sapere quale versione di SDK Platform è installata sul dispositivo dello sviluppatore o in CI. Questo può essere fatto tramite ADB o programmaticamente nel codice dell'applicazione. Conoscere l'API Level del dispositivo aiuta durante il test di comportamenti specifici della versione.

fun logDeviceInfo() {
    with (Build.VERSION) {
        Log.d("SDK_Demo", "SDK_INT: $SDK_INT")
        Log.d("SDK_Demo", "RELEASE: $RELEASE")
        Log.d("SDK_Demo", "CODENAME: $CODENAME")
        Log.d("SDK_Demo", "PREVIEW_SDK_INT: $PREVIEW_SDK_INT")
    }
    // Output: SDK_INT: 35, RELEASE: 15, CODENAME: REL
}