targetSdkVersion: concepte cheie, behavioural changes și Google Play

Ce este targetSdkVersion în Android?

targetSdkVersion — un parametru întreg în build.gradle care declară nivelul API la care aplicația a fost testată. Sistemul Android folosește acest parametru pentru a decide care behavioural changes să fie aplicate aplicației în timpul execuției. Dacă targetSdkVersion = 33, Android aplică toate behavioural changes introduse până la API 33 inclusiv, dar nu aplică modificările API 34+. Dacă targetSdkVersion = 34 — se aplică modificări până la API 34 și așa mai departe.

Diferența cheie dintre targetSdkVersion și minSdkVersion — mecanismul de acțiune. minSdk este verificat o singură dată la instalare și blochează instalarea dacă condiția nu este îndeplinită. targetSdkVersion influențează comportamentul sistemului în runtime pe fiecare dispozitiv, indiferent de versiunea Android pe care rulează aplicația. Aceeași aplicație cu targetSdk 31 se va comporta diferit pe Android 13, 14 și 15, deoarece behavioural changes de peste 31 sunt dezactivate.

Mecanismul targetSdkVersion — este un instrument de compatibilitate inversă încorporat în Android. Fără el, fiecare actualizare a sistemului de operare ar strica mii de aplicații vechi. Google a introdus acest mecanism în Android 2.1 (API Level 7) și de atunci îl folosește ca metodă standard de introducere a noilor reguli de securitate, confidențialitate și gestionare a resurselor fără a perturba funcționarea aplicațiilor existente.

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

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

// Verificarea targetSdk curent în cod
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion conține targetSdk al aplicației
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

În exemplu targetSdk = 36 activează toate behavioural changes Android 16. Codul verifică targetSdkVersion prin context.applicationInfo.targetSdkVersion — aceasta permite determinarea dinamică a modului de compatibilitate activat. Funcția auxiliară este utilă pentru bibliotecile care trebuie să se adapteze la targetSdk al aplicației apelante.

Behavioural Changes: cum targetSdk afectează aplicația

Behavioural changes — sunt modificări ale comportamentului sistemului Android care se aplică doar aplicațiilor cu targetSdkVersion >= unui anumit nivel API. Fiecare versiune majoră nouă de Android introduce behavioural changes, iar dacă aplicația nu actualizează targetSdk, aceste modificări nu intră în vigoare. Un astfel de mecanism permite dezvoltatorilor să actualizeze aplicația în propriul ritm, nu sincron cu lansarea noii versiuni a sistemului de operare.

Scoped Storage (API 29) — una dintre cele mai semnificative behavioural changes. Aplicațiile cu targetSdk 29+ nu pot obține acces direct File la directoarele comune Pictures, Downloads, Music, Documents. În schimb, se utilizează MediaStore pentru multimedia, SAF (Storage Access Framework) pentru fișiere arbitrare și getExternalFilesDir() pentru stocarea proprie. Aplicațiile vechi cu targetSdk 28 și mai jos continuă să funcționeze cu vechiul Full Storage Access, dar acest lucru creează o amenințare de securitate.

POST_NOTIFICATIONS (API 33) — permisiune runtime pentru trimiterea notificărilor. Aplicațiile cu targetSdk 33+ trebuie să solicite permisiunea Manifest.permission.POST_NOTIFICATIONS de la utilizator prin dialogul standard. Dacă permisiunea nu este acordată, NotificationManager.silent() nu afișează notificări utilizatorului. Pe Android 13+ fără această permisiune, notificările push și notificările locale pur și simplu nu se afișează, ceea ce poate reduce semnificativ implicarea utilizatorilor.

Cum să verificați targetSdk curent

Valoarea targetSdkVersion a aplicației poate fi obținută prin ADB: comanda adb shell dumpsys package com.example.myapp | grep targetSdk afișează targetSdk=34. În cod, context.getApplicationInfo().targetSdkVersion returnează un număr întreg. Pentru analitică, este util să logați targetSdk împreună cu android.os.Build.VERSION.SDK_INT pentru a înțelege care behavioural changes sunt efectiv active în fiecare sesiune.

Cerințele Google Play pentru targetSdkVersion (2026)

Google Play stabilește cerințe obligatorii pentru targetSdkVersion pentru toate aplicațiile publicate. Din august 2024 targetSdk minim = 33 (Android 13). Din august 2025 — targetSdk = 34. Se așteaptă ca din august 2026 Google să solicite targetSdk = 35 (Android 15). Aplicațiile noi și actualizările aplicațiilor existente trebuie să îndeplinească aceste cerințe, altfel consola blochează publicarea. Aceasta este politica Google Play, nu o limitare Android Runtime: o aplicație cu targetSdk 34 poate rula pe Android 16, dar nu poate fi publicată în Play Store.

Android App Bundle (AAB) — formatul obligatoriu de publicare din august 2021. APK nu mai este acceptat în Google Play (excepție — aplicații cu dimensiune > 150 MB și unele proiecte legacy). Formatul AAB permite Google să genereze APK-uri optimizate pentru fiecare nivel API și densitate a ecranului, reducând dimensiunea descărcării cu 15-30%. Pentru verificarea targetSdk, Google Play analizează manifestul AAB și, în caz de neconformitate, afișează o eroare cu indicarea valorii minime cerute.

Google Play Console verifică targetSdkVersion nu doar la încărcarea unui nou AAB, ci și la actualizarea aplicației existente. Dacă aplicația dvs. are targetSdk 33, iar Google ridică pragul minim la 34 — nu veți putea lansa nicio actualizare până când nu creșteți targetSdk. Pentru aplicațiile care nu s-au actualizat de mult timp, Google Play poate să le elimine automat din publicare (unpublish).

Cum să actualizați targetSdkVersion fără erori

Actualizarea targetSdkVersion — nu este doar o schimbare a numărului în build.gradle. Fiecare behavioural change poate strica funcționalitatea existentă dacă codul nu este pregătit din timp. Se recomandă începerea pregătirii cu 3-6 luni înainte de termenul Google Play, mai ales dacă aplicația este mare și folosește multe API-uri de sistem.

Procesul pas cu pas: Pasul 1 — studiați behavioural changes pentru noul nivel API în documentația Android Developers (pagina "Behavioural Changes by API Level"). Pasul 2 — creați o ramură targetSdk-update și schimbați targetSdk la noua valoare. Pasul 3 — rulați aplicația pe un emulator sau dispozitiv cu noul nivel API și verificați fiecare funcționalitate legată de modificări. Pasul 4 — remediați erorile: adăugați permisiuni, modificați lucrul cu fișierele, actualizați manifestul.

Pasul 5 — testați pe dispozitive vechi. Creșterea targetSdk nu afectează dispozitivele cu nivel API mai mic decât noul targetSdk, dar behavioural changes se aplică pe toate dispozitivele cu API Level >= targetSdk. Dacă ați crescut targetSdk de la 33 la 34, pe dispozitivele cu API 34+ se vor activa behavioural changes API 34. Pe dispozitivele cu API 33 nimic nu se va schimba.

// Pregătirea pentru 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 restricționează Advertising ID de la API 35
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — identificator indisponibil, folosim MeasurementManager
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Verificare: care behavioural changes sunt active
    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")
        }
    }
}

Clasa AdsManager arată pregătirea pentru Privacy Sandbox (API 35). Advertising ID nu mai este disponibil începând cu API 35 la targetSdk 35+. Funcția getActiveChanges demonstrează modelul corect de verificare a behavioural changes: trebuie să verificați simultan SDK_INT al dispozitivului și targetSdk al aplicației. Doar la îndeplinirea ambelor condiții modificarea este efectiv activă.

Android 15 (API 35): behavioural changes cheie

Android 15 (API 35, Vanilla Ice Cream) introduce câteva behavioural changes critice pe care dezvoltatorii trebuie să le ia în considerare la actualizarea targetSdk la 35. Prima — Privacy Sandbox for Android. Aceasta este inițiativa Google de a înlocui Advertising ID cu API-uri mai private: Topics API (interesele utilizatorului), Protected Audience (remarketing) și Attribution Reporting (conversii). De la API 35, Advertising ID încetează să mai fie un identificator stabil și poate returna o valoare zero.

A doua modificare — Foreground Service Types (API 34, continuat în API 35). Începând cu API 34, fiecare aplicație cu targetSdk 34+ trebuie să specifice tipul serviciului foreground în manifest: dataSync, systemExempted, shortService, location, mediaPlayback și altele. Fără aceasta, sistemul generează ForegroundServiceTypeNotAllowedException. În API 35 a fost adăugat noul tip health și s-a înăsprit verificarea tipurilor existente. Toate serviciile foreground trebuie revizuite.

A treia modificare — restricția SCHEDULE_EXACT_ALARM. Începând cu API 35, aplicațiile cu targetSdk 35+ nu pot folosi SCHEDULE_EXACT_ALARM fără permisiunea explicită a utilizatorului. Sistemul afișează un dialog, iar utilizatorul trebuie să aprobe planificarea exactă. Pentru alarme și temporizatoare, aceasta înseamnă un pas suplimentar în UX. Alternativa — utilizarea alarmelor inexacte cu o marjă de 10 minute.

// Android 15 (API 35): verificare 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+: necesită permisiunea utilizatorului
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // Sub API 35 — alarmele exacte sunt disponibile fără permisiune
        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 și restricția alarmelor — două dintre cele mai critice behavioural changes API 35. Pentru SDK-urile publicitare va fi necesară migrarea la Topics API și Attribution Reporting. Pentru aplicațiile cu alarme și mementouri — adaptarea UX la dialogul de permisiune. Ignorarea acestor modificări va duce la prăbușirea aplicației în runtime pe Android 15 sau la o monetizare publicitară nefuncțională.

Diferența dintre targetSdk și compileSdk

Diferența dintre targetSdkVersion și compileSdkVersion — una dintre cele mai frecvente surse de confuzie printre dezvoltatorii Android. compileSdkVersion — este versiunea SDK împotriva căreia se compilează codul. Aceasta determină care API-uri sunt disponibile în timpul compilării, dar nu influențează comportamentul în runtime. targetSdkVersion — este versiunea sub care aplicația a fost testată, determină care behavioural changes se aplică în runtime. compileSdk poate și trebuie să fie mai mare sau egală cu targetSdk.

Regula este simplă: compileSdk >= targetSdk >= minSdk. compileSdk este de obicei egal cu ultimul nivel API stabil (în 2026 — 36). targetSdk trebuie să fie cât mai mare dintre versiunile sub care ați efectuat testarea. minSdk trebuie să fie cât mai mic pentru o acoperire maximă. Creșterea compileSdk nu necesită testarea behavioural changes — deschide doar accesul la noi API-uri pentru compilator. Creșterea targetSdk necesită un ciclu complet de testare a tuturor behavioural changes.

În practică: dacă doriți să utilizați un nou API din Android 16 (API 36), dar nu ați testat încă behavioural changes API 36, setați compileSdk = 36, targetSdk = 35. Codul se va compila cu noile API-uri, dar behavioural changes API 36 nu se vor aplica. De îndată ce testați toate modificările — creșteți targetSdk la 36.