minSdkVersion: mi ez, hogyan válasszuk ki a minimális Android verziót

Mi az a minSdkVersion Androidban?

minSdkVersion — egy egész paraméter a build.gradle-ben, amely beállítja az alkalmazás telepítéséhez szükséges minimális Android API szintet. Ha az eszköz API szintje a megadott érték alatt van, a PackageManager blokkolja a telepítést, és a Google Play Store elrejti az alkalmazást a keresési eredmények közül az ilyen eszköz számára. A minSdkVersion a build szakaszban az AndroidManifest.xml fájlba íródik a <uses-sdk android:minSdkVersion> tagen keresztül, és minden telepítéskor ellenőrzésre kerül.

A minSdkVersion értéke kompromisszum a közönség lefedettsége és az új API-khoz való hozzáférés között. Minél alacsonyabb a minSdk, annál több eszköz telepítheti az alkalmazást, különösen a fejlődő régiókban, ahol a régi Android okostelefonok népszerűek. Minél magasabb a minSdk, annál kevesebb visszafelé kompatibilitási kód szükséges, és annál több modern API érhető el futásidejű ellenőrzések nélkül. Android Jetpack és az AndroidX könyvtárak sok új API backportját biztosítják a régebbi Android verziókra, lehetővé téve alacsonyabb minSdk választását a funkcionalitás elvesztése nélkül.

A minSdkVersion hatással van a fejlesztés minden szakaszára: statikus elemzés (a lint a minSdk-t használja a figyelmeztetésekhez), függőségi kompatibilitás (a könyvtárak saját minSdk-t igényelhetnek), tesztelés (minSdk-vel rendelkező eszközökön kell tesztelni) és Google Play Console (a közönség lefedettsége a minSdk alapján kerül kiszámításra). A minSdkVersion megváltoztatása az egyik legfelelősségteljesebb döntés a projekt konfigurálásában, mivel hatással van a kódra, a tesztekre és a felhasználói bázisra.

Hol kerül megadásra a minSdkVersion

Build.gradle.kts (Kotlin DSL) — a modern szabvány az Android projektekben. A minSdk paraméter a defaultConfig blokkban van beállítva modul szinten. Az érték felülírható különböző build típusokhoz és termékváltozatokhoz, lehetővé téve a tesztelést alacsonyabb API-kon a fő érték megváltoztatása nélkül.

// build.gradle.kts — a minSdk alapkonfigurációja
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // A minSdk felülírása különböző flavor-ekhez
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

A példában a minSdk = 26 az Android 8.0 Oreo-nak felel meg. Ez egy népszerű érték 2026-ban: az Android Studio Distribution Dashboard szerint csak az eszközök ~15%-át vágja le. A compileSdk = 36 hozzáférést biztosít az Android 16 összes API-jához, a targetSdk = 36 pedig aktiválja a legújabb verzió viselkedésbeli változásait. Debug build-eknél a minSdk csökkenthető a régi emulátorokon való teszteléshez.

Hogyan válasszuk ki a minSdkVersion-t: tényezők és stratégia

A minSdkVersion kiválasztása — stratégiai döntés, amely a célközönség, az API követelmények és a könyvtár-ökoszisztéma elemzésén alapul. Nincs egyetlen helyes érték minden projekt számára. 2026-ban az Android Studio a minSdk = 26 (Android 8.0) értéket ajánlja alap szintként új projektekhez, de B2B alkalmazások vagy vállalati megoldások esetén alacsonyabb vagy magasabb értékek is elfogadhatók.

A minSdkVersion kiválasztásának tényezői

Az első tényező — Distribution Dashboard. Az Android Studio havi rendszerességgel frissített statisztikákat biztosít az aktív eszközökről API szint szerint a Google Play adatai alapján. A minSdkVersion-nak legalább a célpiac aktív eszközeinek 90-95%-át le kell fednie. Nemzetközi alkalmazások esetén, amelyeknek közönsége Afrikában és Délkelet-Ázsiában van, a minSdk-t 21-re (Android 5.0) kell csökkenteni a régi eszközök magas aránya miatt.

A második tényező — függőségi követelmények. Minden könyvtárnak saját minSdkVersion-je van, amely a manifestjében van megadva. Ha egy könyvtár minSdk 29-et igényel, és az alkalmazás — minSdk 26-ot, a build manifest merger hibával végződik. A modern Google Play Services könyvtárak minSdk 21, Firebase — minSdk 21, a legtöbb Jetpack könyvtár — minSdk 21 vagy 26, Compose BOM — minSdk 21 értékkel rendelkezik. A Compose minimális küszöbértéke — API 21.

A harmadik tényező — szükséges API-k. Ha az alkalmazás kulcsfontosságú funkciói olyan API-t igényelnek, amely csak egy bizonyos szinttől érhető el (pl. PhotoPicker — API 34, Predicted Navigation — API 35), ez indokolhatja a minSdk növelését. Azonban gyakrabban használják az AndroidX backportok (Activity Result API, NotificationCompat) és futásidejű ellenőrzések kombinációját az alacsony minSdk megtartásához.

Lépésről lépésre történő kiválasztási stratégia

1. lépés: nyissa meg az Android Studio-t, File → New Project és nézze meg az ajánlott minSdk-t a varázslóban. 2. lépés: ellenőrizze a Distribution Dashboard-ot az Android Studio-ban (View → Tool Windows → App Inspection → Distribution Dashboard). 3. lépés: elemezze a projekt függőségeit — végezze el a build-et és oldja meg a manifest merger konfliktusokat. 4. lépés: értékelje, hogy mely X szintű API-kat használják ténylegesen backport nélkül. 5. lépés: állítsa be a minSdk-t minimális értékként, amely a célközönség 90%+-át lefedi és kompatibilis az összes függőséggel.

Eszközlefedettség: API szintek eloszlása (2026)

Eszközeloszlás API szint szerint — dinamikus mutató, amely negyedévente változik. Az Android Studio Distribution Dashboard 2026. júniusi adatai szerint az aktív Android eszközök körülbelül 85%-a API 26 (Android 8.0) és magasabb, 72%-a API 29 (Android 10) és magasabb, 55%-a API 31 (Android 12) és magasabb szinten fut. A kínai piac saját statisztikával rendelkezik a Google Play Services hiánya miatt számos Huawei eszközön.

GMS eszközök (Google Mobile Services) gyorsabban frissülnek: az API 31+ aránya rajtuk eléri a 68%-ot a Google Play gyártókra vonatkozó kötelező követelményeinek köszönhetően. Non-GMS eszközök (Huawei, Honor, néhány kínai márka) régebbi eloszlással rendelkeznek: az API 31+ aránya rajtuk körülbelül 35%. Ha az alkalmazás a nemzetközi piacra irányul, támaszkodjon a globális statisztikákra. Ha a kínai piacra — vegye figyelembe a non-GMS szegmenst.

Következtetés: nemzetközi alkalmazás esetén a minSdk 26 minimális visszafelé kompatibilitási költségekkel fedi le az eszközök 85%-át. Fejlődő régiókban közönséggel rendelkező alkalmazások esetén a minSdk 21 (97%-os lefedettség) indokolt, de több kódot igényel az elavult API-kkal való munkához. Ellenőrzött eszközparkkal rendelkező Enterprise alkalmazások esetén beállíthatja a minSdk 31-et és teljesen megszabadulhat a fallback kódtól.

Visszafelé kompatibilitás: AndroidX, lint és @RequiresApi

Visszafelé kompatibilitás — a fő nehézség alacsony minSdkVersion esetén. Az AndroidX (korábban Support Library) backportokat biztosít a modern API-khoz régi Android verziókra: AppCompatActivity a Material Designhoz, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat és több tucat egyéb komponens. Az AndroidX megfelelők használata a natív API-k helyett — az első lépés a kompatibilitás felé.

lint (az Android Studio statikus elemzője) átvizsgálja a kódot a minSdkVersion feletti API hívásokra. Ha egy metódus @RequiresApi-val van megjelölve a minSdk-nél magasabb API szinttel, és ellenőrzés nélkül hívják, a lint kiemeli a hibát. A figyelmeztetés elnyomásához használja a @SuppressLint("NewApi") annotációt a metóduson vagy a @RequiresApi(Build.VERSION_CODES.TIRAMISU) annotációt a teljes függvényen. Futásidejű ellenőrzések a Build.VERSION.SDK_INT segítségével — az új API-k biztonságos hívásának elsődleges mechanizmusa régi eszközökön.

// Példa visszafelé kompatibilitásra: PhotoPicker (API 34+) és fallback
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — bármely API szinten működik
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker csak API 34-től érhető el
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // PhotoPicker-t használunk (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (minden verzióban működik)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Ez a metódus nem hívható meg API-n < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Az ImagePickerActivity osztály három szintű visszafelé kompatibilitást mutat be. Az AndroidX-ből származó Activity Result API minden API szinten működik, így az alapvető képválasztáshoz a minSdk nem számít. A PhotoPicker (ACTION_PICK_IMAGES) csak API 34-től érhető el, és SDK_INT ellenőrzés alatt hívódik GetContent fallbackkel. A usePhotoPickerOnly metódus @RequiresApi-val van jelölve — a lint nem engedi ellenőrzés nélkül hívni. Az AndroidX-ből származó AppCompat automatikusan igazítja a témát, fragmenteket és animációkat az operációs rendszer verziójához.

minSdkVersion könyvtárakban és modulokban

Könyvtárak (AAR, JAR) szintén rendelkeznek a manifestjükben megadott minSdkVersion-nal. A könyvtár csatlakoztatásakor a Gradle ellenőrzi a kompatibilitást: ha a könyvtár minSdk-je magasabb, mint az alkalmazás minSdk-je, a build hibával végződik. Nyilvános könyvtárak esetén ajánlott a lehető legalacsonyabb minSdk (a legtöbb esetben 21) megadása, hogy ne korlátozza a fogyasztókat. Ha egy könyvtár API 29+-t igényel, a potenciális felhasználók ~28%-át veszíti el.

Többmodulos projektek különböző minSdkVersion-nal rendelkezhetnek a különböző modulokhoz. Például a :core:network modulnak lehet minSdk 26, a :feature:camera modulnak pedig minSdk 29 (a CameraX specifikus követelményei miatt). A Google Play megköveteli, hogy a fő :app modul minSdk-je alacsonyabb vagy egyenlő legyen az összes függő modul minSdk-jénél. A gyakorlatban egy alkalmazás összes modulja általában azonos minSdk-vel rendelkezik a karbantartás egyszerűsítése érdekében.

// build.gradle.kts — könyvtármodul alacsony minSdk-vel
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // Minimum a maximális lefedettségért
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, backportokat ad hozzá
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

A minSdk = 21 értékkel rendelkező könyvtármodul kompatibilis az eszközök 97%-ával, és nem korlátozza a fogyasztókat. Ha a könyvtár 21 feletti API-kat használ, a fejlesztőnek futásidejű ellenőrzéseket kell hozzáadnia vagy @RequiresApi-t kell megadnia a megfelelő metódusokon. Az AndroidX Core KTX (minSdk 21) backportokat biztosít a Context, Bundle, Locale és más rendszerosztályokhoz, lehetővé téve a könyvtár számára az alacsony minSdk megtartását.

Gyakori hibák a minSdkVersion kiválasztásakor

Hibák a minSdk kiválasztásakor több ezer telepítésbe vagy heteknyi többletfejlesztésbe kerülhetnek. Az első tipikus hiba — a minSdk másolása a projekt sablonból a Distribution Dashboard elemzése nélkül. Sok fejlesztő hagyja a minSdk = 21 értéket az Android Studio sablonból, holott a közönségük számára a minSdk 26 is elég lenne, és csökkentené a SDK_INT ellenőrzések számát a kódban.

A második hiba — túl magas minSdk a piac figyelembevétele nélkül. Ha minSdk = 31 (Android 12) értéket állít be egy nemzetközi alkalmazáshoz, az eszközök ~45%-át veszíti el. Egy induló vállalkozás vagy tömegközönséggel rendelkező alkalmazás számára ez katasztrófa. Mindig ellenőrizze a Distribution Dashboard-ot a minSdk növelése előtt, és használjon A/B tesztelést a Google Play Console-ban, ha nem biztos benne.

A harmadik hiba — a függőségek minSdk-jének figyelmen kívül hagyása. Új könyvtár hozzáadásakor ellenőrizze a minSdk-jét a dokumentációban vagy a POM fájlban. A Firebase ML Kit minSdk 21-et, egyes egyedi kamera könyvtárak minSdk 29-et igényelnek. Ha a manifest merger éles környezetben meghibásodik egy új könyvtár miatt, a javítás napokig tarthat.

// Példa: API kompatibilitás ellenőrzése futásidőben
fun checkFeatureAvailability(): Boolean {
    // Tipikus hiba — API hívás SDK_INT ellenőrzés nélkül
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — PhotoPicker-t használunk
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — MediaStore-t használunk
            true
        }
        else -> {
            // API < 29 — az ACTION_GET_CONTENT-et használjuk
            true
        }
    }
}

Az API szint ellenőrzések helyes architektúrája — when tartományokkal, amelyek lefedik az összes lehetséges értéket a minSdk-től a compileSdk-ig. A kulcsszabály: minden X szintű API hívást védeni kell a VERSION.SDK_INT ellenőrzéssel minden olyan eszköz esetében, amelynek API szintje a minSdk és X között van. A lint segít az ellenőrizetlen hívások észlelésében, de nem tudja garantálni a teljes lefedettséget a dinamikus kód esetében.