API Level: co to jest, wersje API i targetSdk

Co to jest API Level Android?

API Level Android to całkowitoliczbowy identyfikator przypisywany każdej publicznej wersji Android Framework API. Pierwsze wydanie Android 1.0 miało 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żdy nowy API Level może dodawać nowe klasy, metody, stałe, uprawnienia i zmieniać zachowanie istniejących.

API Level nie zwiększa się ściśle o 1 z każdym wydaniem. Na przykład Android 4.4W (Wear) ma API 20, podczas gdy Android 5.0 — API 21. Luki związane są z wewnętrznymi iteracjami i urządzeniami Wear OS. Dla dewelopera ważne jest znać nie nazwę wersji (KitKat, Lollipop, Tiramisu), ale jej API Level — to właśnie on jest używany w kodzie do sprawdzania kompatybilności.

Głównym celem API Level jest wsteczna kompatybilność. Aplikacja skompilowana dla API 34 może działać na urządzeniach z API 34 i niższym (jeśli nie używa nowych API bez sprawdzenia). Android Runtime (ART) sprawdza wywołania API na poziomie systemu i stosuje zmiany behawioralne w zależności od targetSdkVersion aplikacji.

Jak Android obsługuje API Level

Podczas instalacji aplikacji PackageManager sprawdza, czy API Level urządzenia >= minSdkVersion z AndroidManifest.xml. Jeśli warunek nie jest spełniony — instalacja jest blokowana komunikatem "App not installed". Podczas wykonywania Android Runtime monitoruje wywołania API wymagające wyższego API Level i generuje NoSuchMethodError lub UnsatisfiedLinkError, jeśli metoda nie istnieje w bieżącej wersji.

minSdk, targetSdk, compileSdk: różnice i rola każdego parametru

W pliku build.gradle (Module: app) deweloper określa trzy parametry API Level: minSdkVersion, targetSdkVersion i compileSdkVersion. Mylenie ich to jeden z najczęstszych błędów początkujących deweloperów Androida. Każdy parametr odpowiada za inny aspekt kompatybilności, a ich wartości muszą być spójne.

minSdkVersion

minSdkVersion to minimalny API Level, na którym aplikacja może być zainstalowana i uruchomiona. Urządzenia z API Level poniżej minSdk nie widzą aplikacji w Google Play i nie mogą jej zainstalować. Wartość wybiera się na podstawie grupy docelowej: minSdk 21 (Android 5.0) pokrywa 97% urządzeń, minSdk 26 (Android 8.0) — około 85%, minSdk 31 (Android 12) — około 55% (dane z Android Studio Distribution Dashboard, 2026). Im niższe minSdk, tym większy zasięg, ale tym więcej kodu wstecznej kompatybilności jest potrzebne.

targetSdkVersion

targetSdkVersion to API Level, dla którego aplikacja została przetestowana. Android używa targetSdk do stosowania zmian behawioralnych: jeśli aplikacja określa targetSdk 33, system włącza wszystkie zmiany behawioralne wprowadzone w API 33. Jeśli targetSdk to 31, system nie stosuje zmian API 32-33, zachowując kompatybilność ze starym zachowaniem. To najważniejszy parametr dla bezpieczeństwa: Google Play wymaga targetSdk nie starszego niż 1 rok od bieżącego API Level.

compileSdkVersion

compileSdkVersion to wersja Android SDK, dla której kompilowany jest kod. Określa, które API są dostępne podczas kompilacji. compileSdk musi być >= targetSdk i najlepiej równy najnowszemu stabilnemu API Level. Podniesienie compileSdk nie wpływa na zachowanie w czasie wykonywania — tylko na dostępność nowych API dla kompilatora. Po podniesieniu compileSdk należy sprawdzić kod pod kątem przestarzałych API i nowych wymagań uprawnień.

// build.gradle.kts — przykład konfiguracji 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")
}

W przykładzie build.gradle.kts compileSdk = 36 (najnowszy w momencie pisania), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 daje dostęp do wszystkich API Androida 16. targetSdk 36 włącza wszystkie zmiany behawioralne Androida 16. minSdk 26 pokrywa ~85% urządzeń. AndroidX Activity KTX i AppCompat zapewniają wsteczną kompatybilność dla fragmentów i motywów.

AndroidManifest.xml

Parametry minSdk i targetSdk można również określić w AndroidManifest.xml, ale nowoczesne projekty używają build.gradle — wartości z Gradle nadpisują manifest. W manifeście warto określić dla bibliotek i modułów, które nie używają konfiguracji budowania Gradle.

Zmiany behawioralne: jak targetSdk wpływa na zachowanie aplikacji

Zmiany behawioralne to modyfikacje działania systemu Android, które są stosowane tylko do aplikacji z targetSdk >= określonego API Level. Każde nowe wydanie Androida wprowadza zmiany behawioralne, które mogą zepsuć istniejące aplikacje, jeśli nie zostaną zaktualizowane. To kluczowy mechanizm bezpieczeństwa Androida: stare aplikacje działają jak wcześniej, nowe przestrzegają aktualnych zasad.

Główne zmiany behawioralne według wersji

Android 10 (API 29) — Scoped Storage: aplikacje z targetSdk 29+ nie mają bezpośredniego dostępu do współdzielonego systemu plików, tylko przez MediaStore, SAF lub własne przechowywanie. Android 11 (API 30) — Package Visibility: filtr pakietów, aplikacje widzą tylko zainstalowane pakiety, z którymi wchodzą w interakcje. Android 12 (API 31) — Foreground Service Notification: wszystkie usługi pierwszego planu muszą wyświetlić powiadomienie w ciągu 10 sekund od uruchomienia. Android 13 (API 33) — POST_NOTIFICATIONS: uprawnienie czasu wykonania dla powiadomień push. Android 14 (API 34) — Foreground Service Types: obowiązkowa deklaracja typu usługi pierwszego planu w manifeście.

// Obsługa zmian behawioralnych Androida 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) {
        // Uprawnienie POST_NOTIFICATIONS działa tylko z API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Poniżej API 33 uprawnienie nie jest wymagane
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Uprawnienie już przyznane, można wysyłać powiadomienia
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Pokaż wyjaśnienie, dlaczego uprawnienie jest potrzebne
                activity.showRationale()
            }

            else -> {
                // Poproś o uprawnienie
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Utwórz i wyświetl powiadomienie
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Powiadomienie")
            .setContentText("Nowa wiadomość")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Zarejestruj requestPermissionLauncher w Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Uprawnienie przyznane
        }
    }

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

Przykład obsługi POST_NOTIFICATIONS w Kotlinie: sprawdzenie Build.VERSION.SDK_INT >= TIRAMISU, żądanie uprawnienia czasu wykonania przez ActivityResultContracts.RequestPermission, obsługa wyniku w callback. Bez tego uprawnienia aplikacja z targetSdk 33+ nie może wyświetlać powiadomień push. Poniżej API 33 uprawnienie nie jest wymagane — kod sprawdzania zapobiega wywoływaniu niedostępnych API.

Scoped Storage (Android 10+)

Scoped Storage to jedna z najważniejszych zmian behawioralnych. Począwszy od API 29 (targetSdk 29+), aplikacja nie może uzyskać bezpośredniego dostępu do plików w katalogach Pictures, Downloads, Music i Documents. Zamiast tego używa się MediaStore dla multimediów, SAF (Storage Access Framework) dla dowolnych plików i getExternalFilesDir() dla własnego przechowywania. Wyjątkiem są aplikacje z uprawnieniem MANAGE_EXTERNAL_STORAGE, które wymaga zatwierdzenia przez Google Play.

Wymagania Google Play dotyczące API Level i targetSdk

Google Play ustanawia obowiązkowe wymagania dotyczące targetSdkVersion do publikowania aplikacji. Od sierpnia 2024 Google Play wymaga targetSdkVersion >= API 33 (Android 13). Każdego roku próg wzrasta: nowe aplikacje i aktualizacje muszą określać targetSdk nie starszy niż 1 rok od bieżącego głównego API Level. Naruszenie wymogu prowadzi do zablokowania publikacji i usunięcia aplikacji ze sklepu.

Dlaczego Google Play zaostrza wymagania

Głównym powodem jest bezpieczeństwo. Każdy nowy API Level Androida wprowadza zmiany behawioralne zamykające wektory ataków: Scoped Storage (API 29) zapobiega kradzieży plików, POST_NOTIFICATIONS (API 33) chroni przed powiadomieniami spam, Foreground Service Types (API 34) ogranicza ukryte usługi w tle. Aplikacje z niskim targetSdk nie otrzymują tych zabezpieczeń i stają się zagrożeniem dla użytkowników. Google Play nie może pozwolić na przestarzałe aplikacje na nowoczesnych urządzeniach.

Sprawdzanie zgodności z wymaganiami

Google Play Console sprawdza targetSdkVersion podczas przesyłania APK/AAB. Jeśli targetSdk jest poniżej wymaganego — konsola blokuje publikację komunikatem: "Your app currently targets API level X and must target at least API level Y". Deweloper musi zaktualizować build.gradle, skompilować ponownie aplikację, przetestować zmiany behawioralne i przesłać ponownie. Format AAB jest zalecany dla wszystkich nowych publikacji (obowiązkowy od sierpnia 2021).

Sprawdzanie API Level w kodzie: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT to statyczna stała całkowitoliczbowa zawierająca API Level urządzenia, na którym działa aplikacja. To podstawowe narzędzie do sprawdzania wersji Androida w czasie wykonywania. Build.VERSION_CODES zawiera nazwane stałe dla każdego API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Porównanie przez if (SDK_INT >= VERSION_CODES.TIRAMISU) to standardowy wzorzec.

// Przykłady sprawdzania API Level w kodzie Androida
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Podstawowe sprawdzenie API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Adaptacyjne wywołanie API ze sprawdzeniem
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable jest dostępny tylko z API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback dla starych urządzeń
    }

    // 3. Sprawdzenie uprawnienia POST_NOTIFICATIONS (tylko API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Wybór dostawcy obrazów według API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ używa PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ używa Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (wszystkie wersje)
                "get_content"
            }
        }
    }

    // 5. Sprawdzenie w stylu Java przez @TargetApi (dla wstecznej kompatybilności)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Zachowanie Scoped Storage zależy od targetSdk, a nie od SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Informacje o kompilacji dla analityki
    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
        )
    }
}

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

Klasa ApiLevelHelper demonstruje wszystkie główne wzorce sprawdzania API Level: isAtLeastTiramisu z SDK_INT >= VERSION_CODES, getAdaptiveIcon z fallbackiem dla starych wersji, getImagePickerProvider z when-wielogałęziowym, getDeviceApiInfo dla analityki. Kluczowa zasada — nie wywoływać nowych API bez sprawdzenia SDK_INT, w przeciwnym razie aplikacja ulegnie awarii z NoSuchMethodError na starych urządzeniach.

ANT (Android New API) i lint

Android Studio zawiera statyczny analizator lint, który ostrzega przed używaniem API powyżej minSdkVersion. Jeśli metoda jest wywoływana bez sprawdzenia SDK_INT, lint podświetla błąd: "Call requires API level 34 (current min is 26)". Rozwiązania: dodać @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) do metody lub sprawdzenie if SDK_INT. @TargetApi to przestarzała adnotacja, zalecane jest @RequiresApi.

Tabela zgodności API Level i wersji Androida

Tabela API Level to narzędzie referencyjne dla dewelopera. Znając API Level urządzenia, można określić wersję Androida i dostępne funkcje. Tabela zawiera wszystkie główne wydania Androida od API Level 1 (2008) do API Level 36 (2025). Nazwy kodowe (Cupcake, Donut, Tiramisu, VanillaIceCream) są używane wewnętrznie w Google i w VERSION_CODES.

Tabela: progowe API Level dla zmian behawioralnych

Poniższa tabela pokazuje kluczowe API Level wprowadzające zmiany behawioralne, które łamią wsteczną kompatybilność przy podnoszeniu targetSdk: