minSdkVersion: co to je, jak vybrat minimální verzi Androidu

Co je minSdkVersion v Androidu?

minSdkVersion — celočíselný parametr v build.gradle, který nastavuje minimální úroveň API Androidu pro instalaci aplikace. Pokud je úroveň API zařízení nižší než zadaná hodnota, PackageManager blokuje instalaci a Google Play Store skrývá aplikaci z výsledků vyhledávání pro takové zařízení. minSdkVersion se zapisuje do AndroidManifest.xml ve fázi sestavení pomocí tagu <uses-sdk android:minSdkVersion> a kontroluje se při každé instalaci.

Hodnota minSdkVersion je kompromisem mezi pokrytím publika a přístupem k novým API. Čím nižší je minSdk, tím více zařízení může aplikaci nainstalovat, zejména v rozvojových regionech, kde jsou staré Android smartphony populární. Čím vyšší je minSdk, tím méně kódu zpětné kompatibility je potřeba a tím více moderních API je dostupných bez runtime kontrol. Android Jetpack a knihovny AndroidX poskytují backporty mnoha nových API na starší verze Androidu, což umožňuje zvolit nižší minSdk bez ztráty funkcionality.

minSdkVersion ovlivňuje všechny fáze vývoje: statickou analýzu (lint používá minSdk pro varování), kompatibilitu závislostí (knihovny mohou vyžadovat vlastní minSdk), testování (je třeba testovat na zařízeních s minSdk) a Google Play Console (pokrytí publika se vypočítává na základě minSdk). Změna minSdkVersion je jedním z nejzodpovědnějších rozhodnutí při konfiguraci projektu, protože ovlivňuje kód, testy a uživatelskou základnu.

Kde se minSdkVersion uvádí

Build.gradle.kts (Kotlin DSL) — moderní standard v Android projektech. Parametr minSdk se nastavuje v bloku defaultConfig na úrovni modulu. Hodnota může být přepsána pro různé typy sestavení a varianty produktu, což umožňuje testování na nižších API bez změny hlavní hodnoty.

// build.gradle.kts — základní konfigurace minSdk
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"
    }

    // Přepsání minSdk pro různé flavor
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

V příkladu minSdk = 26 odpovídá Android 8.0 Oreo. To je v roce 2026 oblíbená hodnota: podle Android Studio Distribution Dashboard odřezává pouze ~15% zařízení. compileSdk = 36 poskytuje přístup ke všem API Androidu 16 a targetSdk = 36 aktivuje behaviorální změny nejnovější verze. Pro debug sestavení lze minSdk snížit pro testování na starých emulátorech.

Jak vybrat minSdkVersion: faktory a strategie

Výběr minSdkVersion — strategické rozhodnutí založené na analýze cílového publika, požadavků na API a ekosystému knihoven. Neexistuje jediná správná hodnota pro všechny projekty. V roce 2026 Android Studio doporučuje minSdk = 26 (Android 8.0) jako základní úroveň pro nové projekty, ale pro B2B aplikace nebo podniková řešení jsou přijatelné nižší nebo vyšší hodnoty.

Faktory výběru minSdkVersion

První faktor — Distribution Dashboard. Android Studio poskytuje statistiky aktivních zařízení podle úrovně API na základě dat Google Play, aktualizované měsíčně. minSdkVersion by měl pokrývat alespoň 90-95% aktivních zařízení cílového trhu. Pro mezinárodní aplikace s publikem v Africe a jihovýchodní Asii by měl být minSdk snížen na 21 (Android 5.0) kvůli vysokému podílu starých zařízení.

Druhý faktor — požadavky závislostí. Každá knihovna má vlastní minSdkVersion uvedený ve svém manifestu. Pokud knihovna vyžaduje minSdk 29 a aplikace — minSdk 26, sestavení skončí chybou manifest merger. Moderní knihovny Google Play Services mají minSdk 21, Firebase — minSdk 21, většina knihoven Jetpack — minSdk 21 nebo 26, Compose BOM — minSdk 21. Pro Compose je minimální práh — API 21.

Třetí faktor — potřebná API. Pokud klíčová funkčnost aplikace vyžaduje API dostupné pouze od určité úrovně (např. PhotoPicker — API 34, Predicted Navigation — API 35), může to ospravedlnit zvýšení minSdk. Častěji se však používá kombinace backportů AndroidX (Activity Result API, NotificationCompat) a runtime kontrol k zachování nízkého minSdk.

Kroková strategie výběru

Krok 1: otevřete Android Studio, File → New Project a podívejte se na doporučené minSdk v průvodci. Krok 2: zkontrolujte Distribution Dashboard v Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Krok 3: analyzujte závislosti projektu — proveďte sestavení a opravte konflikty manifest merger. Krok 4: vyhodnoťte, která API úrovně X se skutečně používají bez backportů. Krok 5: nastavte minSdk jako minimální hodnotu pokrývající 90%+ cílového publika a kompatibilní se všemi závislostmi.

Pokrytí zařízení: rozdělení úrovní API (2026)

Rozdělení zařízení podle úrovně API — dynamický ukazatel, který se mění každé čtvrtletí. Podle Android Studio Distribution Dashboard k červnu 2026 běží přibližně 85% aktivních Android zařízení na API 26 (Android 8.0) a vyšším, 72% — na API 29 (Android 10) a vyšším, 55% — na API 31 (Android 12) a vyšším. Čínský trh má vlastní statistiku kvůli chybějícím Google Play Services na mnoha zařízeních Huawei.

Zařízení GMS (Google Mobile Services) se aktualizují rychleji: podíl API 31+ na nich dosahuje 68% díky povinným požadavkům Google Play na výrobce. Zařízení non-GMS (Huawei, Honor, některé čínské značky) mají starší rozdělení: podíl API 31+ na nich je přibližně 35%. Pokud je aplikace zaměřena na mezinárodní trh, spoléhejte se na globální statistiky. Pokud na čínský — zohledněte non-GMS segment.

Závěr: pro mezinárodní aplikaci minSdk 26 pokrývá 85% zařízení s minimálními náklady na zpětnou kompatibilitu. Pro aplikace s publikem v rozvojových regionech je minSdk 21 (97% pokrytí) ospravedlnitelný, ale bude vyžadovat více kódu pro práci se zastaralými API. Pro Enterprise aplikace s řízeným parkem zařízení můžete nastavit minSdk 31 a zcela se zbavit fallback kódu.

Zpětná kompatibilita: AndroidX, lint a @RequiresApi

Zpětná kompatibilita — hlavní obtíž při nízkém minSdkVersion. AndroidX (dříve Support Library) poskytuje backporty moderních API na staré verze Androidu: AppCompatActivity pro Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat a desítky dalších komponent. Používání ekvivalentů AndroidX místo nativních API — první krok ke kompatibilitě.

lint (statický analyzátor Android Studio) skenuje kód na volání API nad minSdkVersion. Pokud je metoda označena @RequiresApi s úrovní API vyšší než minSdk a je volána bez kontroly, lint zvýrazní chybu. Pro potlačení varování použijte anotaci @SuppressLint("NewApi") na metodě nebo @RequiresApi(Build.VERSION_CODES.TIRAMISU) na celé funkci. Runtime kontroly prostřednictvím Build.VERSION.SDK_INT — primární mechanismus bezpečného volání nových API na starých zařízeních.

// Příklad zpětné kompatibility: PhotoPicker (API 34+) a 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) — funguje na jakékoli úrovni API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker dostupný pouze od API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Používáme PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (funguje na všech verzích)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Tuto metodu nelze volat na API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Třída ImagePickerActivity demonstruje tři úrovně zpětné kompatibility. Activity Result API z AndroidX funguje na všech úrovních API, takže pro základní výběr obrázku na minSdk nezáleží. PhotoPicker (ACTION_PICK_IMAGES) je dostupný pouze od API 34 a je volán pod kontrolou SDK_INT s fallbackem na GetContent. Metoda usePhotoPickerOnly je označena @RequiresApi — lint ji nedovolí volat bez kontroly. AppCompat z AndroidX automaticky přizpůsobuje téma, fragmenty a animace verzi operačního systému.

minSdkVersion v knihovnách a modulech

Knihovny (AAR, JAR) mají také minSdkVersion uvedený ve svém manifestu. Při připojování knihovny Gradle kontroluje kompatibilitu: pokud je minSdk knihovny vyšší než minSdk aplikace, sestavení selže s chybou. Pro veřejné knihovny se doporučuje uvádět nejnižší možný minSdk (21 ve většině případů), aby neomezovaly spotřebitele. Pokud knihovna vyžaduje API 29+, ztrácí ~28% potenciálních uživatelů.

Vícemodulové projekty mohou mít různé minSdkVersion pro různé moduly. Například modul :core:network může mít minSdk 26 a modul :feature:camera — minSdk 29 (kvůli CameraX s určitými požadavky). Google Play vyžaduje, aby minSdk hlavního modulu :app byl nižší nebo roven minSdk všech závislých modulů. V praxi mají všechny moduly jedné aplikace obvykle stejný minSdk pro zjednodušení údržby.

// build.gradle.kts — modul knihovny s nízkým minSdk
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Minimální pro maximální pokrytí
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, přidává backporty
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Modul knihovny s minSdk = 21 je kompatibilní s 97% zařízení a neomezuje spotřebitele. Pokud knihovna používá API nad 21, vývojář musí přidat runtime kontroly nebo uvést @RequiresApi na příslušných metodách. AndroidX Core KTX (minSdk 21) poskytuje backporty pro Context, Bundle, Locale a další systémové třídy, což umožňuje knihovně udržet nízký minSdk.

Typické chyby při výběru minSdkVersion

Chyby při výběru minSdk mohou stát tisíce instalací nebo týdny dalšího vývoje. První typická chyba — kopírování minSdk z šablony projektu bez analýzy Distribution Dashboard. Mnoho vývojářů nechává minSdk = 21 z šablony Android Studio, i když by pro jejich publikum bylo minSdk 26 dostačující a snížilo by počet kontrol SDK_INT v kódu.

Druhá chyba — příliš vysoké minSdk bez ohledu na trh. Pokud nastavíte minSdk = 31 (Android 12) pro mezinárodní aplikaci, ztrácíte ~45% zařízení. Pro startup nebo aplikaci s masovým publikem je to katastrofa. Vždy kontrolujte Distribution Dashboard před zvýšením minSdk a používejte A/B testování v Google Play Console, pokud si nejste jisti.

Třetí chyba — ignorování minSdk závislostí. Při přidávání nové knihovny zkontrolujte její minSdk v dokumentaci nebo souboru POM. Firebase ML Kit vyžaduje minSdk 21, některé vlastní knihovny pro fotoaparát vyžadují minSdk 29. Pokud manifest merger selže v produkci kvůli nové knihovně, oprava může trvat dny.

// Příklad: kontrola kompatibility API za běhu
fun checkFeatureAvailability(): Boolean {
    // Typická chyba — volání API bez kontroly SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — používáme PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — používáme MediaStore
            true
        }
        else -> {
            // API < 29 — používáme ACTION_GET_CONTENT
            true
        }
    }
}

Správná architektura kontrol úrovně API — when s rozsahy pokrývajícími všechny možné hodnoty od minSdk do compileSdk. Klíčové pravidlo: každé volání API úrovně X musí být chráněno kontrolou VERSION.SDK_INT pro všechna zařízení s úrovní API od minSdk do X. lint pomáhá detekovat nezkontrolovaná volání, ale nemůže zaručit úplné pokrytí pro dynamický kód.