API Level: ce este, versiuni API și targetSdk

Ce este API Level Android?

API Level Android este un identificator întreg atribuit fiecărei versiuni publice a Android Framework API. Prima lansare Android 1.0 avea 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. Fiecare API Level nou poate adăuga clase, metode, constante, permisiuni noi și poate modifica comportamentul celor existente.

API Level nu crește strict cu 1 la fiecare lansare. De exemplu, Android 4.4W (Wear) are API 20, în timp ce Android 5.0 — API 21. Decalajele sunt legate de iterațiile interne și dispozitivele Wear OS. Pentru dezvoltator, este important să cunoască nu numele versiunii (KitKat, Lollipop, Tiramisu), ci API Level-ul acesteia — acesta este ceea ce se folosește în cod pentru verificări de compatibilitate.

Scopul principal al API Level este compatibilitatea retroactivă. O aplicație compilată împotriva API 34 poate rula pe dispozitive cu API 34 și mai jos (dacă nu folosește API-uri noi fără verificare). Android Runtime (ART) verifică apelurile API la nivel de sistem și aplică modificări comportamentale în funcție de targetSdkVersion al aplicației.

Cum gestionează Android API Level

La instalarea unei aplicații, PackageManager verifică dacă API Level al dispozitivului >= minSdkVersion din AndroidManifest.xml. Dacă condiția nu este îndeplinită — instalarea este blocată cu mesajul "App not installed". În timpul execuției, Android Runtime monitorizează apelurile API care necesită un API Level mai mare și generează NoSuchMethodError sau UnsatisfiedLinkError dacă metoda lipsește din versiunea curentă.

minSdk, targetSdk, compileSdk: diferențe și rolul fiecărui parametru

În fișierul build.gradle (Module: app), dezvoltatorul specifică trei parametri API Level: minSdkVersion, targetSdkVersion și compileSdkVersion. Confundarea lor este una dintre cele mai frecvente greșeli ale dezvoltatorilor Android începători. Fiecare parametru este responsabil pentru un aspect diferit al compatibilității, iar valorile lor trebuie să fie consistente.

minSdkVersion

minSdkVersion este API Level minim la care aplicația poate fi instalată și rulată. Dispozitivele cu API Level sub minSdk nu văd aplicația în Google Play și nu o pot instala. Valoarea este aleasă pe baza publicului țintă: minSdk 21 (Android 5.0) acoperă 97% din dispozitive, minSdk 26 (Android 8.0) — aproximativ 85%, minSdk 31 (Android 12) — aproximativ 55% (date din Android Studio Distribution Dashboard, 2026). Cu cât minSdk este mai mic, cu atât acoperirea este mai mare, dar cu atât mai mult cod de compatibilitate retroactivă este necesar.

targetSdkVersion

targetSdkVersion este API Level împotriva căruia a fost testată aplicația. Android folosește targetSdk pentru a aplica modificări comportamentale: dacă aplicația specifică targetSdk 33, sistemul activează toate modificările comportamentale introduse în API 33. Dacă targetSdk este 31, sistemul nu aplică modificările API 32-33, păstrând compatibilitatea cu comportamentul vechi. Acesta este cel mai important parametru pentru securitate: Google Play cere targetSdk nu mai vechi de 1 an de la API Level curent.

compileSdkVersion

compileSdkVersion este versiunea Android SDK împotriva căreia este compilat codul. Determină ce API-uri sunt disponibile la momentul compilării. compileSdk trebuie să fie >= targetSdk și, ideal, egal cu ultimul API Level stabil. Creșterea compileSdk nu afectează comportamentul în timpul execuției — doar disponibilitatea noilor API-uri pentru compilator. După creșterea compileSdk, trebuie verificat codul pentru API-uri învechite și noi cerințe de permisiuni.

// build.gradle.kts — exemplu de configurare 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")
}

În exemplul build.gradle.kts, compileSdk = 36 (cel mai recent la momentul scrierii), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 oferă acces la toate API-urile Android 16. targetSdk 36 activează toate modificările comportamentale Android 16. minSdk 26 acoperă ~85% din dispozitive. AndroidX Activity KTX și AppCompat asigură compatibilitate retroactivă pentru fragmente și teme.

AndroidManifest.xml

Parametrii minSdk și targetSdk pot fi specificați și în AndroidManifest.xml, dar proiectele moderne folosesc build.gradle — valorile din Gradle suprascriu manifestul. În manifest, poate fi util să specificați pentru biblioteci și module care nu folosesc configurația de build Gradle.

Modificări comportamentale: cum afectează targetSdk comportamentul aplicației

Modificările comportamentale sunt modificări ale modului de funcționare a sistemului Android care sunt aplicate doar aplicațiilor cu targetSdk >= un anumit API Level. Fiecare nouă lansare Android introduce modificări comportamentale care pot strica aplicațiile existente dacă nu sunt actualizate. Acesta este un mecanism cheie de securitate Android: aplicațiile vechi continuă să funcționeze ca înainte, cele noi urmează regulile curente.

Principalele modificări comportamentale pe versiuni

Android 10 (API 29) — Scoped Storage: aplicațiile cu targetSdk 29+ nu au acces direct la sistemul de fișiere partajat, doar prin MediaStore, SAF sau propriul spațiu de stocare. Android 11 (API 30) — Package Visibility: filtru de pachete, aplicațiile văd doar pachetele instalate cu care interacționează. Android 12 (API 31) — Foreground Service Notification: toate serviciile de prim-plan trebuie să afișeze o notificare în 10 secunde de la pornire. Android 13 (API 33) — POST_NOTIFICATIONS: permisiune de execuție pentru notificări push. Android 14 (API 34) — Foreground Service Types: declararea obligatorie a tipului de serviciu de prim-plan în manifest.

// Gestionarea modificărilor comportamentale 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) {
        // Permisiunea POST_NOTIFICATIONS funcționează doar cu API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Sub API 33 permisiunea nu este necesară
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Permisiune deja acordată, se pot trimite notificări
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Afișează explicația de ce este necesară permisiunea
                activity.showRationale()
            }

            else -> {
                // Solicită permisiune
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Creează și afișează notificare
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Notificare")
            .setContentText("Mesaj nou")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Înregistrează requestPermissionLauncher în Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Permisiune acordată
        }
    }

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

Exemplu de gestionare a POST_NOTIFICATIONS în Kotlin: verificarea Build.VERSION.SDK_INT >= TIRAMISU, solicitarea permisiunii de execuție prin ActivityResultContracts.RequestPermission, gestionarea rezultatului într-un callback. Fără această permisiune, o aplicație cu targetSdk 33+ nu poate afișa notificări push. Sub API 33, permisiunea nu este necesară — codul de verificare împiedică apelarea API-urilor indisponibile.

Scoped Storage (Android 10+)

Scoped Storage este una dintre cele mai semnificative modificări comportamentale. Începând cu API 29 (targetSdk 29+), aplicația nu poate obține acces direct la fișiere în directoarele Pictures, Downloads, Music și Documents. În schimb, se folosește MediaStore pentru multimedia, SAF (Storage Access Framework) pentru fișiere arbitrare și getExternalFilesDir() pentru spațiul propriu de stocare. Excepția sunt aplicațiile cu permisiunea MANAGE_EXTERNAL_STORAGE, care necesită aprobarea Google Play.

Cerințele Google Play pentru API Level și targetSdk

Google Play stabilește cerințe obligatorii de targetSdkVersion pentru publicarea aplicațiilor. Din august 2024, Google Play cere targetSdkVersion >= API 33 (Android 13). În fiecare an, pragul crește: aplicațiile și actualizările noi trebuie să specifice targetSdk nu mai vechi de 1 an de la API Level principal curent. Încălcarea cerinței duce la blocarea publicării și eliminarea aplicației din magazin.

De ce Google Play înăsprește cerințele

Motivul principal este securitatea. Fiecare API Level nou Android introduce modificări comportamentale care închid vectori de atac: Scoped Storage (API 29) previne furtul de fișiere, POST_NOTIFICATIONS (API 33) protejează împotriva notificărilor spam, Foreground Service Types (API 34) limitează serviciile de fundal ascunse. Aplicațiile cu targetSdk scăzut nu primesc aceste protecții și devin o amenințare pentru utilizatori. Google Play nu poate permite aplicații învechite pe dispozitive moderne.

Verificarea conformității cu cerințele

Google Play Console verifică targetSdkVersion la încărcarea APK/AAB. Dacă targetSdk este sub cerință — consola blochează publicarea cu mesajul: "Your app currently targets API level X and must target at least API level Y". Dezvoltatorul trebuie să actualizeze build.gradle, să recompileze aplicația, să testeze modificările comportamentale și să reîncarce. Formatul AAB este recomandat pentru toate publicările noi (obligatoriu din august 2021).

Verificarea API Level în cod: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT este o constantă întreagă statică ce conține API Level al dispozitivului pe care rulează aplicația. Este instrumentul principal pentru verificări ale versiunii Android în timpul execuției. Build.VERSION_CODES conține constante denumite pentru fiecare API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Comparația prin if (SDK_INT >= VERSION_CODES.TIRAMISU) este modelul standard.

// Exemple de verificare a API Level în codul Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Verificare de bază API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Apel API adaptiv cu verificare
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable este disponibil doar cu API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback pentru dispozitive vechi
    }

    // 3. Verificare permisiune POST_NOTIFICATIONS (doar API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Selectarea furnizorului de imagini după API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ folosește PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ folosește Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (toate versiunile)
                "get_content"
            }
        }
    }

    // 5. Verificare stil Java prin @TargetApi (pentru compatibilitate retroactivă)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Comportamentul Scoped Storage depinde de targetSdk, nu de SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informații de build pentru analitică
    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
        )
    }
}

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

Clasa ApiLevelHelper demonstrează toate modelele principale de verificare a API Level: isAtLeastTiramisu cu SDK_INT >= VERSION_CODES, getAdaptiveIcon cu fallback pentru versiuni vechi, getImagePickerProvider cu when multi-ramură, getDeviceApiInfo pentru analitică. Regula cheie este să nu apelați API-uri noi fără a verifica SDK_INT, altfel aplicația se va bloca cu NoSuchMethodError pe dispozitive vechi.

ANT (Android New API) și lint

Android Studio include analizorul static lint, care avertizează despre utilizarea API-urilor peste minSdkVersion. Dacă o metodă este apelată fără verificarea SDK_INT, lint o evidențiază ca eroare: "Call requires API level 34 (current min is 26)". Soluții: adăugați @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) la metodă sau o verificare if a SDK_INT. @TargetApi este o adnotare învechită, @RequiresApi este recomandat.

Tabel de corespondență între API Level și versiunile Android

Tabelul API Level este un instrument de referință pentru dezvoltator. Cunoscând API Level al dispozitivului, puteți determina versiunea Android și funcțiile disponibile. Tabelul listează toate versiunile principale Android de la API Level 1 (2008) la API Level 36 (2025). Numele de cod (Cupcake, Donut, Tiramisu, VanillaIceCream) sunt folosite intern în Google și în VERSION_CODES.

Tabel: API Level prag pentru modificări comportamentale

Următorul tabel arată API Level-urile cheie care introduc modificări comportamentale ce strică compatibilitatea retroactivă la creșterea targetSdk: