API Level: mi ez, API verziók és targetSdk

Mi az API Level Android?

API Level Android egy egész számú azonosító, amelyet az Android Framework API minden nyilvános kiadásához hozzárendelnek. Az első kiadás, az Android 1.0 API Level 1-gyel rendelkezett, 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. Minden új API Level új osztályokat, metódusokat, konstansokat, engedélyeket adhat hozzá és megváltoztathatja a meglévők viselkedését.

Az API Level nem szigorúan 1-gyel nő minden kiadással. Például az Android 4.4W (Wear) API 20-szal rendelkezik, míg az Android 5.0 — API 21-gyel. A hiányosságok belső iterációkkal és Wear OS eszközökkel kapcsolatosak. A fejlesztő számára fontos, hogy ne a verzió nevét (KitKat, Lollipop, Tiramisu) ismerje, hanem az API Level-t — ezt használják a kódban a kompatibilitási ellenőrzésekhez.

Az API Level fő célja a visszafelé kompatibilitás. Az API 34-re lefordított alkalmazás működhet API 34 és alacsonyabb verziójú eszközökön (ha nem használ új API-kat ellenőrzés nélkül). Az Android Runtime (ART) rendszerszinten ellenőrzi az API-hívásokat, és az alkalmazás targetSdkVersion-jétől függően alkalmazza a viselkedésbeli változásokat.

Hogyan kezeli az Android az API Level-t

Alkalmazás telepítésekor a PackageManager ellenőrzi, hogy az eszköz API Level >= minSdkVersion az AndroidManifest.xml-ből. Ha a feltétel nem teljesül — a telepítés blokkolva lesz a "App not installed" üzenettel. Futás közben az Android Runtime figyeli azokat az API-hívásokat, amelyek magasabb API Level-t igényelnek, és NoSuchMethodError vagy UnsatisfiedLinkError hibát generál, ha a metódus nem található az aktuális verzióban.

minSdk, targetSdk, compileSdk: különbségek és az egyes paraméterek szerepe

A build.gradle fájlban (Module: app) a fejlesztő három API Level paramétert ad meg: minSdkVersion, targetSdkVersion és compileSdkVersion. Ezek összekeverése az egyik leggyakoribb hiba a kezdő Android-fejlesztők körében. Minden paraméter a kompatibilitás más-más aspektusáért felelős, és értékeiknek konzisztensnek kell lenniük.

minSdkVersion

minSdkVersion az a minimális API Level, amelyen az alkalmazás telepíthető és futtatható. A minSdk-nél alacsonyabb API Level-lel rendelkező eszközök nem látják az alkalmazást a Google Play-ben, és nem tudják telepíteni. Az értéket a célközönség alapján választják ki: minSdk 21 (Android 5.0) az eszközök 97%-át fedi le, minSdk 26 (Android 8.0) — kb. 85%, minSdk 31 (Android 12) — kb. 55% (adatok az Android Studio Distribution Dashboard-ból, 2026). Minél alacsonyabb a minSdk, annál nagyobb a lefedettség, de annál több visszafelé kompatibilitási kódra van szükség.

targetSdkVersion

targetSdkVersion az az API Level, amelyen az alkalmazást tesztelték. Az Android a targetSdk-t használja a viselkedésbeli változások alkalmazására: ha az alkalmazás targetSdk 33-at ad meg, a rendszer bekapcsolja az API 33-ban bevezetett összes viselkedésbeli változást. Ha targetSdk 31, a rendszer nem alkalmazza az API 32-33 változásait, megtartva a kompatibilitást a régi viselkedéssel. Ez a legfontosabb paraméter a biztonság szempontjából: a Google Play megköveteli, hogy a targetSdk ne legyen 1 évnél régebbi a jelenlegi API Level-től.

compileSdkVersion

compileSdkVersion az Android SDK verziója, amelyre a kódot lefordítják. Meghatározza, hogy mely API-k érhetők el fordítási időben. A compileSdk-nak >= targetSdk kell lennie, és ideális esetben egyenlő a legújabb stabil API Level-lel. A compileSdk emelése nem befolyásolja a futásidejű viselkedést — csak az új API-k elérhetőségét a fordító számára. A compileSdk emelése után ellenőrizni kell a kódot elavult API-k és új engedélykövetelmények szempontjából.

// build.gradle.kts — példa API Level konfigurációra
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")
}

A build.gradle.kts példában a compileSdk = 36 (a legújabb az írás pillanatában), targetSdk = 36, minSdk = 26 (Android 8.0). A compileSdk 36 hozzáférést biztosít az összes Android 16 API-hoz. A targetSdk 36 bekapcsolja az összes Android 16 viselkedésbeli változást. A minSdk 26 az eszközök ~85%-át fedi le. Az AndroidX Activity KTX és AppCompat visszafelé kompatibilitást biztosít a fragmentekhez és témákhoz.

AndroidManifest.xml

A minSdk és targetSdk paraméterek az AndroidManifest.xml-ben is megadhatók, de a modern projektek a build.gradle-t használják — a Gradle értékei felülírják a manifestet. A manifestben hasznos lehet megadni a könyvtárak és modulok számára, amelyek nem használnak Gradle build konfigurációt.

Viselkedésbeli változások: hogyan befolyásolja a targetSdk az alkalmazás viselkedését

Viselkedésbeli változások az Android rendszer működésének módosításai, amelyeket csak a targetSdk >= egy adott API Level rendelkező alkalmazásokra alkalmaznak. Minden új Android-kiadás olyan viselkedésbeli változásokat vezet be, amelyek meglévő alkalmazásokat törhetnek meg, ha nem frissítik őket. Ez az Android egyik legfontosabb biztonsági mechanizmusa: a régi alkalmazások továbbra is úgy működnek, mint korábban, az újak a jelenlegi szabályokat követik.

Főbb viselkedésbeli változások verzióként

Android 10 (API 29) — Scoped Storage: a targetSdk 29+ rendelkező alkalmazásoknak nincs közvetlen hozzáférésük a megosztott fájlrendszerhez, csak MediaStore-on, SAF-en vagy saját tárolón keresztül. Android 11 (API 30) — Package Visibility: csomagszűrő, az alkalmazások csak azokat a telepített csomagokat látják, amelyekkel kölcsönhatásba lépnek. Android 12 (API 31) — Foreground Service Notification: minden előtér-szolgáltatásnak értesítést kell megjelenítenie az indítást követő 10 másodpercen belül. Android 13 (API 33) — POST_NOTIFICATIONS: futásidejű engedély a push értesítésekhez. Android 14 (API 34) — Foreground Service Types: az előtér-szolgáltatás típusának kötelező deklarálása a manifestben.

// Android 13 (API 33) viselkedésbeli változásainak kezelése: 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) {
        // A POST_NOTIFICATIONS engedély csak API 33+ működik
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // API 33 alatt nincs szükség engedélyre
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Az engedély már megadva, értesítések küldhetők
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Magyarázat megjelenítése, miért szükséges az engedély
                activity.showRationale()
            }

            else -> {
                // Engedély kérése
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Értesítés létrehozása és megjelenítése
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Értesítés")
            .setContentText("Új üzenet")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// requestPermissionLauncher regisztrálása az Activity-ben
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Engedély megadva
        }
    }

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

Példa a POST_NOTIFICATIONS kezelésére Kotlinban: ellenőrizze a Build.VERSION.SDK_INT >= TIRAMISU-t, kérjen futásidejű engedélyt az ActivityResultContracts.RequestPermission segítségével, kezelje az eredményt egy callback-ben. Ezen engedély nélkül a targetSdk 33+ rendelkező alkalmazás nem tud push értesítéseket megjeleníteni. Az API 33 alatt nincs szükség engedélyre — az ellenőrző kód megakadályozza a nem elérhető API-k hívását.

Scoped Storage (Android 10+)

Scoped Storage az egyik legjelentősebb viselkedésbeli változás. Az API 29-től (targetSdk 29+) kezdődően az alkalmazás nem kaphat közvetlen fájlhozzáférést a Pictures, Downloads, Music és Documents könyvtárakhoz. Ehelyett a MediaStore-t használják a médiafájlokhoz, a SAF-ot (Storage Access Framework) tetszőleges fájlokhoz és a getExternalFilesDir()-t a saját tárolóhoz. Kivételt képeznek a MANAGE_EXTERNAL_STORAGE engedéllyel rendelkező alkalmazások, amelyekhez Google Play jóváhagyás szükséges.

A Google Play API Level és targetSdk követelményei

Google Play kötelező targetSdkVersion követelményeket állapít meg az alkalmazások közzétételéhez. 2024 augusztusa óta a Google Play megköveteli a targetSdkVersion >= API 33 (Android 13) verziót. Évente emelkedik a küszöb: az új alkalmazásoknak és frissítéseknek a jelenlegi fő API Level-től számított 1 évnél nem régebbi targetSdk-t kell megadniuk. A követelmény megsértése a közzététel blokkolásához és az alkalmazás áruházból való eltávolításához vezet.

Miért szigorítja a Google Play a követelményeket

A fő ok a biztonság. Minden új Android API Level olyan viselkedésbeli változásokat vezet be, amelyek lezárják a támadási vektorokat: a Scoped Storage (API 29) megakadályozza a fájllopást, a POST_NOTIFICATIONS (API 33) véd a spam értesítésektől, a Foreground Service Types (API 34) korlátozza a rejtett háttérszolgáltatásokat. Az alacsony targetSdk-val rendelkező alkalmazások nem kapják meg ezeket a védelmeket, és veszélyt jelentenek a felhasználókra. A Google Play nem engedheti meg az elavult alkalmazásokat a modern eszközökön.

A követelményeknek való megfelelés ellenőrzése

A Google Play Console ellenőrzi a targetSdkVersion-t az APK/AAB feltöltésekor. Ha a targetSdk az előírt alatt van — a konzol blokkolja a közzétételt a következő üzenettel: "Your app currently targets API level X and must target at least API level Y". A fejlesztőnek frissítenie kell a build.gradle-t, újra kell fordítania az alkalmazást, tesztelnie kell a viselkedésbeli változásokat, és újra fel kell töltenie. Az AAB formátum ajánlott minden új közzétételhez (2021 augusztusa óta kötelező).

API Level ellenőrzése a kódban: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT egy statikus egész számú konstans, amely az alkalmazást futtató eszköz API Level-jét tartalmazza. Ez az elsődleges eszköz az Android verziójának futásidejű ellenőrzéséhez. A Build.VERSION_CODES névvel ellátott konstansokat tartalmaz minden API Level-hez: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Az if (SDK_INT >= VERSION_CODES.TIRAMISU) összehasonlítás a szabványos minta.

// Példák API Level ellenőrzésére Android kódban
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Alapvető API Level ellenőrzés
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Adaptív API hívás ellenőrzéssel
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // Az AdaptiveIconDrawable csak API 26 (Android 8) rendelkezésre áll
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback régi eszközökhöz
    }

    // 3. POST_NOTIFICATIONS engedély ellenőrzése (csak API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Képszolgáltató kiválasztása API Level alapján
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ PhotoPicker-t használ
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ Intent ACTION_OPEN_DOCUMENT-ot használ
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (minden verzió)
                "get_content"
            }
        }
    }

    // 5. Java-stílusú ellenőrzés @TargetApi segítségével (visszafelé kompatibilitáshoz)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // A Scoped Storage viselkedése a targetSdk-től függ, nem az SDK_INT-tól
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Fordítási információk elemzéshez
    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
        )
    }
}

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

Az ApiLevelHelper osztály bemutatja az összes fő API Level-ellenőrzési mintát: isAtLeastTiramisu SDK_INT >= VERSION_CODES-szel, getAdaptiveIcon fallback-kel a régi verziókhoz, getImagePickerProvider when-többágú elágazással, getDeviceApiInfo elemzéshez. A kulcsszabály: ne hívjon új API-kat az SDK_INT ellenőrzése nélkül, különben az alkalmazás NoSuchMethodError hibával összeomlik a régi eszközökön.

ANT (Android New API) és lint

Az Android Studio tartalmazza a lint statikus elemzőt, amely figyelmeztet a minSdkVersion feletti API-k használatára. Ha egy metódust SDK_INT ellenőrzés nélkül hívnak meg, a lint hibaként jelöli meg: "Call requires API level 34 (current min is 26)". Megoldások: adjon hozzá @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)-et a metódushoz, vagy egy if-ellenőrzést az SDK_INT-ra. A @TargetApi egy elavult annotáció, a @RequiresApi ajánlott.

API Level és Android verziók megfelelési táblázata

API Level táblázat egy referenciaeszköz a fejlesztő számára. Az eszköz API Level-jének ismeretében meghatározhatja az Android verzióját és az elérhető funkciókat. A táblázat felsorolja az összes főbb Android-kiadást az API Level 1-től (2008) az API Level 36-ig (2025). A kódneveket (Cupcake, Donut, Tiramisu, VanillaIceCream) a Google-on belül és a VERSION_CODES-ban használják.

Táblázat: küszöb-API Level-ek a viselkedésbeli változásokhoz

A következő táblázat azokat a kulcsfontosságú API Level-eket mutatja, amelyek olyan viselkedésbeli változásokat vezetnek be, amelyek megtörik a visszafelé kompatibilitást a targetSdk emelésekor: