targetSdkVersion: concetti chiave, behavioural changes e Google Play

Cos'è targetSdkVersion in Android?

targetSdkVersion è un parametro intero in build.gradle che dichiara l'API Level contro cui l'app è stata testata. Il sistema Android usa questo parametro per decidere quali behavioural changes applicare all'app in fase di esecuzione. Se targetSdkVersion = 33, Android applica tutti i behavioural changes introdotti fino ad API 33 inclusa, ma non applica le modifiche di API 34+. Se targetSdkVersion = 34 — vengono applicate le modifiche fino ad API 34, e così via.

La differenza principale tra targetSdkVersion e minSdkVersion è il meccanismo d'azione. minSdk viene controllato una volta durante l'installazione e blocca l'installazione se la condizione non è soddisfatta. targetSdkVersion influisce sul comportamento runtime del sistema su ogni dispositivo, indipendentemente dalla versione Android su cui l'app è in esecuzione. La stessa app con targetSdk 31 si comporterà diversamente su Android 13, 14 e 15, perché i behavioural changes superiori a 31 sono disabilitati.

Il meccanismo di targetSdkVersion è uno strumento di retrocompatibilità integrato in Android. Senza di esso, ogni aggiornamento del OS romperebbe migliaia di app vecchie. Google ha introdotto questo meccanismo in Android 2.1 (API Level 7) e da allora lo utilizza come metodo standard per introdurre nuove regole di sicurezza, privacy e gestione delle risorse senza rompere le applicazioni esistenti.

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

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

// Verifica del targetSdk corrente nel codice
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion contiene il targetSdk dell'app
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

Nell'esempio, targetSdk = 36 abilita tutti i behavioural changes di Android 16. Il codice controlla targetSdkVersion tramite context.applicationInfo.targetSdkVersion — questo consente di determinare dinamicamente quale modalità di compatibilità è attiva. La funzione di supporto è utile per le librerie che devono adattarsi al targetSdk dell'applicazione chiamante.

Behavioural Changes: come targetSdk influisce sull'app

I behavioural changes sono modifiche al comportamento del sistema Android che si applicano solo alle app con targetSdkVersion >= un determinato API Level. Ogni nuova release major di Android introduce behavioural changes e se un'app non aggiorna targetSdk, queste modifiche non entrano in vigore. Questo meccanismo consente agli sviluppatori di aggiornare la propria app al proprio ritmo, piuttosto che in modo sincrono con una nuova release del OS.

Scoped Storage (API 29) è uno dei behavioural changes più significativi. Le app con targetSdk 29+ non possono ottenere accesso File diretto alle directory condivise Pictures, Downloads, Music, Documents. Invece, MediaStore viene utilizzato per i file multimediali, SAF (Storage Access Framework) per file arbitrari e getExternalFilesDir() per l'archiviazione privata. Le app vecchie con targetSdk 28 e inferiori continuano a funzionare con il legacy Full Storage Access, ma questo crea un rischio per la sicurezza.

POST_NOTIFICATIONS (API 33) è un'autorizzazione runtime per l'invio di notifiche. Le app con targetSdk 33+ devono richiedere l'autorizzazione Manifest.permission.POST_NOTIFICATIONS all'utente tramite il dialogo standard. Se l'autorizzazione non viene concessa, NotificationManager.silent() non mostra le notifiche all'utente. Su Android 13+ senza questa autorizzazione, le notifiche push e le notifiche locali semplicemente non vengono visualizzate, il che può ridurre significativamente il coinvolgimento degli utenti.

Come verificare il targetSdk corrente

Il valore di targetSdkVersion può essere ottenuto tramite ADB: il comando adb shell dumpsys package com.example.myapp | grep targetSdk restituisce targetSdk=34. Nel codice, context.getApplicationInfo().targetSdkVersion restituisce un numero intero. Per l'analisi, è utile registrare targetSdk insieme a android.os.Build.VERSION.SDK_INT per capire quali behavioural changes sono effettivamente attivi in ogni sessione.

Requisiti di Google Play per targetSdkVersion (2026)

Google Play stabilisce requisiti obbligatori di targetSdkVersion per tutte le app pubblicate. Da agosto 2024, il targetSdk minimo = 33 (Android 13). Da agosto 2025, targetSdk = 34. Si prevede che da agosto 2026, Google richiederà targetSdk = 35 (Android 15). Le nuove app e gli aggiornamenti delle app esistenti devono soddisfare questi requisiti, altrimenti la console blocca la pubblicazione. Questa è una policy di Google Play, non una limitazione di Android Runtime: un'app con targetSdk 34 può funzionare su Android 16, ma non può essere pubblicata sul Play Store.

Android App Bundle (AAB) è il formato di pubblicazione obbligatorio da agosto 2021. APK non è più accettato in Google Play (eccetto per app più grandi di 150 MB e alcuni progetti legacy). Il formato AAB consente a Google di generare APK ottimizzati per ogni API Level e densità dello schermo, riducendo la dimensione del download del 15-30%. Per verificare targetSdk, Google Play analizza il manifest AAB e emette un errore con il valore minimo richiesto se non conforme.

La Google Play Console verifica targetSdkVersion non solo durante il caricamento di un nuovo AAB, ma anche durante l'aggiornamento di un'app esistente. Se la tua app ha targetSdk 33 e Google aumenta la soglia minima a 34 — non potrai rilasciare alcun aggiornamento finché non aumenti targetSdk. Per le app che non vengono aggiornate da molto tempo, Google Play può rimuoverle automaticamente dalla pubblicazione (unpublish).

Come aggiornare targetSdkVersion senza errori

Aggiornare targetSdkVersion non significa solo cambiare un numero in build.gradle. Ogni behavioural change può rompere la funzionalità esistente se il codice non viene preparato in anticipo. Si consiglia di iniziare la preparazione 3-6 mesi prima della scadenza di Google Play, specialmente se l'app è grande e utilizza molte API di sistema.

Processo passo dopo passo: Passo 1 — studia i behavioural changes per il nuovo API Level nella documentazione di Android Developers (pagina "Behavioural Changes by API Level"). Passo 2 — crea un branch targetSdk-update e modifica targetSdk al nuovo valore. Passo 3 — esegui l'app su un emulatore o dispositivo con il nuovo API Level e verifica ogni funzionalità correlata alle modifiche. Passo 4 — correggi gli errori: aggiungi autorizzazioni, modifica la gestione dei file, aggiorna il manifest.

Passo 5 — testa su dispositivi vecchi. Aumentare targetSdk non influisce sui dispositivi con API Level inferiore al nuovo targetSdk, ma i behavioural changes si applicano a tutti i dispositivi con API Level >= targetSdk. Se hai aumentato targetSdk da 33 a 34, sui dispositivi con API 34+ i behavioural changes dell'API 34 verranno attivati. Sui dispositivi con API 33 non cambierà nulla.

// Preparazione per 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 limita Advertising ID da API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identificatore non disponibile, usa MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Verifica: quali behavioural changes sono attivi
    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 classe AdsManager mostra la preparazione per Privacy Sandbox (API 35). Advertising ID diventa non disponibile a partire da API 35 con targetSdk 35+. La funzione getActiveChanges mostra il modello corretto per verificare i behavioural changes: è necessario controllare sia SDK_INT del dispositivo che targetSdk dell'app. Solo quando entrambe le condizioni corrispondono, la modifica è effettivamente attiva.

Android 15 (API 35): principali behavioural changes

Android 15 (API 35, Vanilla Ice Cream) introduce diversi behavioural changes critici che gli sviluppatori devono considerare quando aggiornano targetSdk a 35. Primo — Privacy Sandbox for Android. Questa è l'iniziativa di Google per sostituire Advertising ID con API più private: Topics API (interessi dell'utente), Protected Audience (retargeting) e Attribution Reporting (conversioni). A partire da API 35, Advertising ID cessa di essere un identificatore stabile e può restituire un valore nullo.

Il secondo cambiamento — Foreground Service Types (API 34, continuato in API 35). A partire da API 34, ogni app con targetSdk 34+ deve specificare il tipo di servizio in primo piano nel manifest: dataSync, systemExempted, shortService, location, mediaPlayback e altri. Senza questo, il sistema genera ForegroundServiceTypeNotAllowedException. In API 35, è stato aggiunto un nuovo tipo health e la validazione dei tipi esistenti è stata inasprita. Tutti i servizi in primo piano devono essere revisionati.

Il terzo cambiamento — restrizione su SCHEDULE_EXACT_ALARM. A partire da API 35, le app con targetSdk 35+ non possono utilizzare SCHEDULE_EXACT_ALARM senza esplicita autorizzazione dell'utente. Il sistema mostra un dialogo e l'utente deve approvare la pianificazione esatta. Per sveglie e timer, ciò significa un passaggio UX aggiuntivo. Un'alternativa è utilizzare sveglie non esatte con un margine di 10 minuti.

// Android 15 (API 35): verifica di 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+: autorizzazione utente richiesta
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Sotto API 35 — sveglie esatte disponibili senza autorizzazione
        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 e la restrizione delle sveglie sono i due behavioural changes più critici di API 35. Gli SDK pubblicitari dovranno migrare a Topics API e Attribution Reporting. Per le app con sveglie e promemoria — adattamento UX per il dialogo di autorizzazione. Ignorare queste modifiche porterà a crash dell'app in runtime su Android 15 o a una monetizzazione pubblicitaria interrotta.

Differenza tra targetSdk e compileSdk

La differenza tra targetSdkVersion e compileSdkVersion è una delle fonti più comuni di confusione tra gli sviluppatori Android. compileSdkVersion è la versione dell'SDK contro cui il codice viene compilato. Determina quali API sono disponibili al momento della compilazione, ma non influisce sul comportamento runtime. targetSdkVersion è la versione contro cui l'app è testata — determina quali behavioural changes si applicano in fase di esecuzione. compileSdk può e deve essere maggiore o uguale a targetSdk.

La regola è semplice: compileSdk >= targetSdk >= minSdk. compileSdk è solitamente uguale all'ultimo API Level stabile (nel 2026 — 36). targetSdk dovrebbe essere il più alto possibile tra le versioni che hai testato. minSdk dovrebbe essere il più basso possibile per la massima copertura. Aumentare compileSdk non richiede test dei behavioural changes — apre solo l'accesso a nuove API per il compilatore. Aumentare targetSdk richiede un ciclo completo di test di tutti i behavioural changes.

In pratica: se vuoi utilizzare una nuova API da Android 16 (API 36) ma non hai ancora testato i behavioural changes di API 36, imposta compileSdk = 36, targetSdk = 35. Il codice verrà compilato con le nuove API, ma i behavioural changes di API 36 non verranno applicati. Una volta testate tutte le modifiche — aumenta targetSdk a 36.