API Level: co to je, verze API a targetSdk

Co je API Level Android?

API Level Android je celočíselný identifikátor přiřazený každému veřejnému vydání Android Framework API. První vydání Android 1.0 mělo 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. Každá nová úroveň API může přidávat nové třídy, metody, konstanty, oprávnění a měnit chování stávajících.

API Level se striktně nezvyšuje o 1 s každým vydáním. Například Android 4.4W (Wear) má API 20, zatímco Android 5.0 — API 21. Mezery souvisejí s interními iteracemi a zařízeními Wear OS. Pro vývojáře je důležité znát nikoli název verze (KitKat, Lollipop, Tiramisu), ale její API Level — právě ten se používá v kódu pro kontroly kompatibility.

Klíčovým účelem API Level je zpětná kompatibilita. Aplikace zkompilovaná proti API 34 může fungovat na zařízeních s API 34 a nižším (pokud nepoužívá nová API bez kontroly). Android Runtime (ART) kontroluje volání API na úrovni systému a aplikuje změny chování v závislosti na targetSdkVersion aplikace.

Jak Android zpracovává API Level

Při instalaci aplikace PackageManager zkontroluje, zda je API Level zařízení >= minSdkVersion z AndroidManifest.xml. Pokud podmínka není splněna — instalace je blokována zprávou "App not installed". Během běhu Android Runtime monitoruje volání API, která vyžadují vyšší API Level, a generuje NoSuchMethodError nebo UnsatisfiedLinkError, pokud metoda v aktuální verzi neexistuje.

minSdk, targetSdk, compileSdk: rozdíly a role každého parametru

V souboru build.gradle (Module: app) vývojář specifikuje tři parametry API Level: minSdkVersion, targetSdkVersion a compileSdkVersion. Jejich zaměňování je jedním z nejčastějších chyb začínajících vývojářů pro Android. Každý parametr je zodpovědný za jiný aspekt kompatibility a jejich hodnoty musí být konzistentní.

minSdkVersion

minSdkVersion je minimální API Level, na kterém lze aplikaci nainstalovat a spustit. Zařízení s API Level nižším než minSdk nevidí aplikaci v Google Play a nemohou ji nainstalovat. Hodnota se volí na základě cílového publika: minSdk 21 (Android 5.0) pokrývá 97% zařízení, minSdk 26 (Android 8.0) — asi 85%, minSdk 31 (Android 12) — asi 55% (data z Android Studio Distribution Dashboard, 2026). Čím nižší je minSdk, tím větší je pokrytí, ale tím více kódu pro zpětnou kompatibilitu je potřeba.

targetSdkVersion

targetSdkVersion je API Level, proti kterému byla aplikace testována. Android používá targetSdk k aplikování změn chování: pokud aplikace specifikuje targetSdk 33, systém aktivuje všechny změny chování zavedené v API 33. Pokud je targetSdk 31, systém neaplikuje změny API 32-33 a zachovává kompatibilitu se starým chováním. Toto je nejdůležitější parametr pro bezpečnost: Google Play vyžaduje targetSdk ne starší než 1 rok od aktuálního API Level.

compileSdkVersion

compileSdkVersion je verze Android SDK, proti které je kód kompilován. Určuje, která API jsou k dispozici v době kompilace. compileSdk musí být >= targetSdk a ideálně roven nejnovější stabilní úrovni API. Zvýšení compileSdk neovlivňuje chování za běhu — pouze dostupnost nových API pro kompilátor. Po zvýšení compileSdk je třeba zkontrolovat kód na zastaralá API a nové požadavky na oprávnění.

// build.gradle.kts — příklad konfigurace 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")
}

V příkladu build.gradle.kts je compileSdk = 36 (nejnovější v době psaní), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 poskytuje přístup ke všem API Androidu 16. targetSdk 36 aktivuje všechny změny chování Androidu 16. minSdk 26 pokrývá ~85% zařízení. AndroidX Activity KTX a AppCompat poskytují zpětnou kompatibilitu pro fragmenty a motivy.

AndroidManifest.xml

Parametry minSdk a targetSdk lze také specifikovat v AndroidManifest.xml, ale moderní projekty používají build.gradle — hodnoty z Gradle přepisují manifest. V manifestu může být užitečné specifikovat pro knihovny a moduly, které nepoužívají konfiguraci sestavení Gradle.

Změny chování: jak targetSdk ovlivňuje chování aplikace

Změny chování jsou úpravy fungování systému Android, které se aplikují pouze na aplikace s targetSdk >= určitého API Level. Každé nové vydání Androidu zavádí změny chování, které mohou zlomit stávající aplikace, pokud nejsou aktualizovány. Toto je klíčový bezpečnostní mechanismus Androidu: staré aplikace fungují dál jako dříve, nové se řídí aktuálními pravidly.

Hlavní změny chování podle verzí

Android 10 (API 29) — Scoped Storage: aplikace s targetSdk 29+ nemají přímý přístup ke sdílenému souborovému systému, pouze přes MediaStore, SAF nebo vlastní úložiště. Android 11 (API 30) — Package Visibility: filtr balíčků, aplikace vidí pouze nainstalované balíčky, se kterými interagují. Android 12 (API 31) — Foreground Service Notification: všechny služby na popředí musí do 10 sekund po spuštění zobrazit oznámení. Android 13 (API 33) — POST_NOTIFICATIONS: oprávnění za běhu pro push oznámení. Android 14 (API 34) — Foreground Service Types: povinná deklarace typu služby na popředí v manifestu.

// Zpracování změn chování 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) {
        // Oprávnění POST_NOTIFICATIONS funguje pouze s API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Pod API 33 není oprávnění vyžadováno
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Oprávnění již uděleno, oznámení lze odesílat
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Zobrazit vysvětlení, proč je oprávnění potřeba
                activity.showRationale()
            }

            else -> {
                // Požádat o oprávnění
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Vytvořit a zobrazit oznámení
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Oznámení")
            .setContentText("Nová zpráva")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Zaregistrovat requestPermissionLauncher v Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Oprávnění uděleno
        }
    }

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

Příklad zpracování POST_NOTIFICATIONS v Kotlinu: kontrola Build.VERSION.SDK_INT >= TIRAMISU, žádost o oprávnění za běhu přes ActivityResultContracts.RequestPermission, zpracování výsledku v callbacku. Bez tohoto oprávnění aplikace s targetSdk 33+ nemůže zobrazovat push oznámení. Pod API 33 není oprávnění vyžadováno — kontrolní kód zabraňuje volání nedostupných API.

Scoped Storage (Android 10+)

Scoped Storage je jednou z nejvýznamnějších změn chování. Počínaje API 29 (targetSdk 29+) aplikace nemůže získat přímý přístup k souborům v adresářích Pictures, Downloads, Music a Documents. Místo toho se používá MediaStore pro multimédia, SAF (Storage Access Framework) pro libovolné soubory a getExternalFilesDir() pro vlastní úložiště. Výjimkou jsou aplikace s oprávněním MANAGE_EXTERNAL_STORAGE, které vyžaduje schválení Google Play.

Požadavky Google Play na API Level a targetSdk

Google Play stanovuje povinné požadavky na targetSdkVersion pro publikování aplikací. Od srpna 2024 Google Play vyžaduje targetSdkVersion >= API 33 (Android 13). Každý rok se práh zvyšuje: nové aplikace a aktualizace musí specifikovat targetSdk ne starší než 1 rok od aktuálního hlavního API Level. Porušení požadavku vede k blokování publikace a odstranění aplikace z obchodu.

Proč Google Play zpřísňuje požadavky

Hlavním důvodem je bezpečnost. Každá nová úroveň API Androidu zavádí změny chování, které uzavírají vektory útoků: Scoped Storage (API 29) zabraňuje krádeži souborů, POST_NOTIFICATIONS (API 33) chrání před spamovými oznámeními, Foreground Service Types (API 34) omezuje skryté služby na pozadí. Aplikace s nízkým targetSdk tyto ochrany nedostávají a stávají se hrozbou pro uživatele. Google Play nemůže povolit zastaralé aplikace na moderních zařízeních.

Kontrola shody s požadavky

Google Play Console kontroluje targetSdkVersion při nahrávání APK/AAB. Pokud je targetSdk pod požadavkem — konzole blokuje publikaci zprávou: "Your app currently targets API level X and must target at least API level Y". Vývojář musí aktualizovat build.gradle, překompilovat aplikaci, otestovat změny chování a znovu nahrát. Formát AAB je doporučen pro všechna nová publikování (povinný od srpna 2021).

Kontrola API Level v kódu: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT je statická celočíselná konstanta obsahující API Level zařízení, na kterém aplikace běží. Je to primární nástroj pro kontroly verze Androidu za běhu. Build.VERSION_CODES obsahuje pojmenované konstanty pro každou úroveň API: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Porovnání pomocí if (SDK_INT >= VERSION_CODES.TIRAMISU) je standardní vzor.

// Příklady kontroly API Level v kódu Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Základní kontrola API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Adaptivní volání API s kontrolou
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable je k dispozici pouze s API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback pro stará zařízení
    }

    // 3. Kontrola oprávnění POST_NOTIFICATIONS (pouze API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Výběr poskytovatele obrázků podle API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ používá PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ používá Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (všechny verze)
                "get_content"
            }
        }
    }

    // 5. Kontrola ve stylu Java přes @TargetApi (pro zpětnou kompatibilitu)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Chování Scoped Storage závisí na targetSdk, ne na SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informace o sestavení pro analytiku
    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
        )
    }
}

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

Třída ApiLevelHelper demonstruje všechny hlavní vzory kontroly API Level: isAtLeastTiramisu s SDK_INT >= VERSION_CODES, getAdaptiveIcon s fallbackem pro staré verze, getImagePickerProvider s when-vícevětvením, getDeviceApiInfo pro analytiku. Klíčové pravidlo — nevolat nová API bez kontroly SDK_INT, jinak aplikace spadne s NoSuchMethodError na starých zařízeních.

ANT (Android New API) a lint

Android Studio obsahuje statický analyzátor lint, který varuje před používáním API nad minSdkVersion. Pokud je metoda volána bez kontroly SDK_INT, lint ji zvýrazní jako chybu: "Call requires API level 34 (current min is 26)". Řešení: přidat @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) k metodě nebo if-kontrolu SDK_INT. @TargetApi je zastaralá anotace, doporučuje se @RequiresApi.

Tabulka shody API Level a verzí Androidu

Tabulka API Level je referenční nástroj pro vývojáře. Znalostí API Level zařízení lze určit verzi Androidu a dostupné funkce. Tabulka uvádí všechna hlavní vydání Androidu od API Level 1 (2008) do API Level 36 (2025). Kódová jména (Cupcake, Donut, Tiramisu, VanillaIceCream) se používají interně v Google a v VERSION_CODES.

Tabulka: prahové API Level pro změny chování

Následující tabulka ukazuje klíčové API Level, které zavádějí změny chování, které lámou zpětnou kompatibilitu při zvyšování targetSdk: