compileSdkVersion: alapok, új API-k és konfiguráció a Gradle-ben

Mi az a compileSdkVersion Androidban?

compileSdkVersion — egy egész paraméter a build.gradle-ben, amely meghatározza, hogy az Android SDK mely verziója ellen kell fordítani a kódot. Amikor android.* vagy androidx.* osztályokat használó kódot ír, a fordító ellenőrzi azokat a compileSdk megadott verziójában elérhető API-kkal. Ha egy metódus az API 36-ban jelent meg, és a compileSdk = 35, a kód nem fordul le. Ha a compileSdk = 36 — a kód lefordul, de egy API 35-ös eszközön a metódus ellenőrzés nélküli meghívásakor hiba lép fel.

A compileSdkVersion az Android SDK Platform-ból töltődik be, amelyet az SDK Manageren keresztül telepítenek az Android Studio-ban. Minden API Level rendelkezik saját platformmal: android-21, android-29, android-34, android-35, android-36. A platform tartalmazza az android.jar-t — osztályok, metódusok és konstansok készletét, amellyel a Kotlin/Java fordító dolgozik. Ha a platform nincs telepítve, a Gradle automatikusan letölti azt az sdkmanager-en keresztül az első build alkalmával.

AGP (Android Gradle Plugin) 8.7+ verziója javasolja a compileSdk egész számként való megadását a compileSdk = 36 használatával Kotlin DSL-ben, az android- előtag nélkül. A compileSdk megadható a compileSdkVersion 36 használatával Groovy DSL-ben vagy a compileSdkPreview segítségével az SDK előzetes verzióihoz (developer previews). A compileSdkPreview a jövőbeli API Level-ek tesztelésére szolgál a hivatalos kiadás előtt.

// build.gradle.kts — compileSdkVersion konfiguráció
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — legutóbbi stabil API Level (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Alternatívaként: compileSdkPreview előzetes verziókhoz
// compileSdkPreview = "Baklava"

A példában a compileSdk = 36 hozzáférést biztosít az Android 16 (Baklava) összes API-jához. Az Android SDK Platform 36-ot telepíteni kell az SDK Manager-ben. A "Baklava" nevű compileSdkPreview használható az instabil API-k tesztelésére a platform hivatalos kiadása előtt. A kiadás után a preview-t a stabil compileSdk = 36 váltja fel.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Három API Level paraméter a build.gradle-ben — compileSdkVersion, targetSdkVersion és minSdkVersion — gyakran összekeverik. Mindegyik a kompatibilitás más-más aspektusáért felelős, és értékeiknek a compileSdk >= targetSdk >= minSdk szabály szerint kell összhangban lenniük. minSdk — alsó határ: az ennél alacsonyabb eszközök nem látják az alkalmazást. targetSdk — tesztelési pont: a behavioural changes eddig a szintig kapcsolódnak be. compileSdk — plafon: az e szint feletti API-k nem érhetők el a fordító számára.

Kulcsfontosságú gyakorlati szabály: a compileSdk emelhető bármilyen eszközön történő tesztelés nélkül. Ez egy biztonságos művelet, amely csak egy új android.jar verziót ad a fordítónak. Az egyetlen kockázat — a deprecated API-k, amelyek eltávolíthatók a platform új verziójában, de ez a fordítás szakaszában kiderül és könnyen javítható. A targetSdk emelése viszont teljes QA ciklust igényel.

Miért lehet a compileSdk magasabb a targetSdk-nál? Képzelje el, hogy megjelent az Android 16 (API 36) új API-kkal, amelyeket használni szeretne a kódban, de az API 36 behavioural changes-eit még nem tesztelte. Beállítja a compileSdk = 36-ot (új API-k elérhetők), a targetSdk = 35-öt (API 36 behavioural changes-ei kikapcsolva). A kód lefordul, az új metódusokat SDK_INT ellenőrzések alatt használja, és az API 36 behavioural changes-ei nem törik meg az alkalmazást, mert a targetSdk = 35.

Példák helyes kombinációkra

compileSdk = 36, targetSdk = 36, minSdk = 26 — teljes kompatibilitás a legújabb API-kkal és behavioural changes-szel, 85%-os eszközlefedettség. compileSdk = 36, targetSdk = 34, minSdk = 26 — új API-k elérhetők, behavioural changes csak API 34-ig. compileSdk = 35, targetSdk = 36 — helytelen: compileSdk alacsonyabb, mint targetSdk, az API 36 nem érhető el, bár a behavioural changes 36 aktív.

Hogyan frissítsük a compileSdkVersion-t: lépésről lépésre útmutató

A compileSdkVersion frissítése — az egyik legegyszerűbb és legbiztonságosabb művelet egy Android projektben. A targetSdk-tól eltérően nem igényli a behavioural changes hosszadalmas tesztelését. Azonban néhány lépést el kell végezni a fordítási hibák és a deprecated figyelmeztetések elkerülése érdekében.

1. lépés — telepítse az új platformot az SDK Manageren keresztül az Android Studio-ban: Tools → SDK Manager → SDK Platforms → válassza ki az új API Level-t. Ha nem telepíti a platformot, a Gradle megpróbálja automatikusan letölteni, de ez lassíthatja az első build-et. 2. lépés — módosítsa a compileSdk-t a build.gradle-ben az új értékre. 3. lépés — végezze el a build-et (Build → Make Project) és javítsa ki a fordítási hibákat.

4. lépés — ellenőrizze a deprecated API-kat. A compileSdk emelése után egyes metódusok @Deprecated jelölést kaphatnak a "removed in API X" megjegyzéssel. Az Android Studio áthúzással kiemeli őket és figyelmeztetést ad. Cserélje le a deprecated hívásokat új alternatívákra. Ha az alternatíva magasabb API Level-t igényel, mint a minSdk, adjon hozzá runtime ellenőrzést. 5. lépés — ellenőrizze a dependencies-eket: egyes könyvtárak meghatározott compileSdk verziót igényelhetnek. Az AGP 8.7+ a compileSdk = 36-ot javasolja.

// A compileSdk emelése után: deprecated API-k cseréje
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ELŐTT: deprecated metódus (eltávolítható az új API-ban)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Lehet, hogy deprecated az API 36-ban
    }

    // UTÁN: új alternatíva (ha elérhető)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Új API a compileSdk 36-ból
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Példa új API-ra
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

A CompileSdkMigration osztály a helyes migrációs mintát mutatja. A régi memoryClass metódus eltávolítható az új API-ban — a fordító hibát ad. Az új alternatíva, a getMemoryClassSafe csak API 36+-on érhető el, ezért SDK_INT >= BAKLAVA ellenőrzés alatt hívódik meg. A régi eszközökhöz @Suppress("DEPRECATION")-nel ellátott fallback használatos.

Munka új API-kkal: feltételes ellenőrzések és fallback

Az új API-k, amelyek a compileSdkVersion emelésének köszönhetően érhetők el, nem hívhatók meg közvetlenül, ha a minSdkVersion alacsonyabb ennél az API Level-nél. Runtime ellenőrzés nélkül az alkalmazás AbstractMethodError, NoSuchMethodError vagy VerifyError hibával összeomlik a régi eszközökön. A fő védelmi mechanizmus — a Build.VERSION.SDK_INT ellenőrzése az új API csak elegendő API Level esetén történő meghívásával és fallback a régi verziókhoz.

AndroidX számos új API backport-ját biztosítja, lehetővé téve a modern metódusok használatát még alacsony compileSdk mellett is. Például az Activity Result API az androidx.activity:activity-ktx:1.9.3-ból az Android összes verzióján működik API 14-től kezdve. A NotificationCompat az AndroidX-ből lehetővé teszi a modern értesítések használatát régi API-ken. A PhotoPicker az ActivityResultContracts.PickVisualMedia segítségével érhető el API 34+-tól.

// Új API biztonságos meghívása compileSdk 36 és minSdk 26 mellett
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: új metódus a színkezeléshez
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Új API a compileSdk 36-ból — API 36+ szükséges
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: kézi formázás régi API-khoz
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport nem szükséges — SDK_INT ellenőrzés
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Használat Activity-ben
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

A NewApiHelper osztály bemutatja az új Color.toArgbHexString API (hipotetikus API 36) biztonságos meghívását fallback formázással a régi verziókhoz. A kulcs elv: a compileSdk hozzáférést biztosít az új metódusok kódban történő meghívásához, de a runtime SDK_INT ellenőrzés véd az összeomlástól a régi eszközökön. SDK_INT ellenőrzés nélkül a minSdk 26 és compileSdk 36 paraméterű alkalmazás összeomlik Android 8-15-ön.

AGP (Android Gradle Plugin) és compileSdkVersion

Android Gradle Plugin (AGP) — az Android alkalmazások fő build eszköze. Minden AGP verzió egy meghatározott compileSdkVersion tartományt támogat. Az AGP 8.7.x (2026-ban kiadva) compileSdk >= 34-et igényel és compileSdk = 36-ot javasol. Az AGP 8.5.x a compileSdk 33-35-öt támogatja. Ha a compileSdk alacsonyabb az AGP minimális értékénél, a build a "The SDK platform (X) is not supported by this version of the Android Gradle Plugin" hibával végződik.

NDK (Native Development Kit) szintén kötődik a compileSdkVersion-hoz. Ha a projekt natív C/C++ kódot használ az NDK-n keresztül, a compileSdk meghatározza a header fájlok és könyvtárak verzióját. Az NDK r27+ a compileSdk 36-ot javasolja. A .so fájlokat tartalmazó könyvtárak esetén a compileSdk az APP_MIN_SDK_VERSION-en keresztül az Application.mk-ben befolyásolja a natív kód minimális API Level-jét.

Gradle (7.6+) és Kotlin (2.0+) szintén befolyásolják a compileSdk-val való kompatibilitást. Az AGP 8.7+ Gradle 8.9+ és Kotlin 2.0+ verziót igényel. A compileSdk emelésekor ajánlott az AGP, Gradle és Kotlin frissítése a legújabb stabil verziókra. Ellenőrizze a kompatibilitást a hivatalos Android Gradle Plugin compatibility táblázatban.

Tipikus problémák a compileSdk emelésekor

Problémák a compileSdkVersion emelésekor három kategóriába sorolhatók: compilation errors, deprecated warnings és runtime incompatibilities. Compilation errors — a metódusok eltávolításra kerültek az API-ból és a kód nem fordul le. Deprecated warnings — a metódusok @Deprecated jelölést kaptak, a kód figyelmeztetésekkel fordul le. Runtime incompatibilities — az új API-k kötelezőek bizonyos funkciókhoz, és hibát okoznak elégtelen API Level esetén az eszközön.

Az első tipikus probléma — "Cannot resolve symbol X". Ez azt jelenti, hogy egy osztály vagy metódus eltávolításra került a publikus API-ból az SDK új verziójában. Megoldás: találjon alternatívát az új platformon vagy használja az AndroidX megfelelőt. Például az AsyncTaskLoader osztály deprecated volt API 28-ban, és eltávolításra került a publikus API-ból az újabb verziókban. Alternatíva — Kotlin Coroutines vagy WorkManager.

A második probléma — a metódus aláírásának megváltozása. Az API új verziójában a metódus megváltoztathatta a paraméterek számát vagy típusait. A Kotlin/Java fordító a "None of the following functions can be called with the arguments supplied" hibát adja. Megoldás: frissítse a metódushívást az új aláíráshoz, vagy adjon hozzá SDK_INT ellenőrzést a régi aláírás meghívásával a régi eszközökhöz.

// Problémák megoldása a compileSdk emelésekor
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Probléma: a hasSystemFeature metódus megváltoztatta az aláírását API 36-ban
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Új aláírás: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Régi aláírás: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Probléma: osztály eltávolítva, AndroidX megfelelőt használunk
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Az android.app.FragmentManager (eltávolítva) helyett használjuk
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

A CompileSdkProblemFixer osztály megoldja a tipikus problémákat: a megváltozott hasSystemFeature aláírás (hipotetikus változás API 36-ban) SDK_INT ellenőrzésen keresztül kerül kezelésre a metódus helyes verziójának meghívásával. Az eltávolított android.app.FragmentManager osztály AndroidX megfelelőre lett cserélve. A régi hívásokhoz, ahol nincs alternatíva, @Suppress("DEPRECATION") használatos a megtartás okáról szóló megjegyzéssel.