minSdkVersion: co to jest, jak wybrać minimalną wersję Androida

Czym jest minSdkVersion w Androidzie?

minSdkVersion — całkowitoliczbowy parametr w build.gradle, który określa minimalny poziom API Androida wymagany do instalacji aplikacji. Jeśli poziom API urządzenia jest niższy niż podana wartość, PackageManager blokuje instalację, a Google Play Store ukrywa aplikację w wynikach wyszukiwania dla takiego urządzenia. minSdkVersion jest zapisywany w AndroidManifest.xml na etapie budowania przez tag <uses-sdk android:minSdkVersion> i jest sprawdzany przy każdej instalacji.

Wartość minSdkVersion to kompromis między zasięgiem odbiorców a dostępem do nowych API. Im niższe minSdk, tym więcej urządzeń może zainstalować aplikację, szczególnie w rozwijających się regionach, gdzie popularne są stare smartfony z Androidem. Im wyższe minSdk, tym mniej kodu kompatybilności wstecznej jest wymagane i więcej nowoczesnych API jest dostępnych bez sprawdzeń w czasie wykonania. Android Jetpack i biblioteki AndroidX dostarczają backporty wielu nowych API na stare wersje Androida, co pozwala wybrać niższe minSdk bez utraty funkcjonalności.

minSdkVersion wpływa na wszystkie etapy programowania: analizę statyczną (lint używa minSdk do ostrzeżeń), kompatybilność zależności (biblioteki mogą wymagać własnego minSdk), testowanie (należy testować na urządzeniach z minSdk) i Google Play Console (zasięg odbiorców jest obliczany na podstawie minSdk). Zmiana minSdkVersion to jedna z najbardziej odpowiedzialnych decyzji przy konfiguracji projektu, ponieważ wpływa na kod, testy i bazę użytkowników.

Gdzie określa się minSdkVersion

Build.gradle.kts (Kotlin DSL) — nowoczesny standard w projektach Android. Parametr minSdk jest ustawiany w bloku defaultConfig na poziomie modułu. Wartość może być nadpisywana dla różnych typów budowania i wariantów produktu, co pozwala testować na niższych API bez zmiany głównej wartości.

// build.gradle.kts — podstawowa konfiguracja 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"
    }

    // Nadpisywanie minSdk dla różnych flavor
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

W przykładzie minSdk = 26 odpowiada Android 8.0 Oreo. To popularna wartość w 2026 roku: odcina tylko ~15% urządzeń według Android Studio Distribution Dashboard. compileSdk = 36 daje dostęp do wszystkich API Androida 16, a targetSdk = 36 włącza zmiany behawioralne najnowszej wersji. Dla kompilacji debug minSdk można obniżyć do testowania na starych emulatorach.

Jak wybrać minSdkVersion: czynniki i strategia

Wybór minSdkVersion — strategiczna decyzja oparta na analizie docelowej grupy odbiorców, wymagań API i ekosystemu bibliotek. Nie ma jednej prawidłowej wartości dla wszystkich projektów. W 2026 roku Android Studio zaleca minSdk = 26 (Android 8.0) jako podstawowy poziom dla nowych projektów, ale dla aplikacji B2B lub rozwiązań korporacyjnych dopuszczalne są niższe lub wyższe wartości.

Czynniki wyboru minSdkVersion

Pierwszy czynnik — Distribution Dashboard. Android Studio dostarcza statystyki aktywnych urządzeń według poziomu API na podstawie danych Google Play, aktualizowane co miesiąc. minSdkVersion powinien pokrywać co najmniej 90-95% aktywnych urządzeń na rynku docelowym. Dla międzynarodowych aplikacji z odbiorcami w Afryce i Azji Południowo-Wschodniej minSdk warto obniżyć do 21 (Android 5.0) ze względu na wysoki udział starych urządzeń.

Drugi czynnik — wymagania zależności. Każda biblioteka ma własny minSdkVersion określony w swoim manifeście. Jeśli biblioteka wymaga minSdk 29, a aplikacja — minSdk 26, budowanie zakończy się błędem manifest merger. Nowoczesne biblioteki Google Play Services mają minSdk 21, Firebase — minSdk 21, większość bibliotek Jetpack — minSdk 21 lub 26, Compose BOM — minSdk 21. Dla Compose minimalny próg — API 21.

Trzeci czynnik — wymagane API. Jeśli kluczowa funkcjonalność aplikacji wymaga API dostępnego tylko od określonego poziomu (np. PhotoPicker — API 34, Predicted Navigation — API 35), może to uzasadniać podniesienie minSdk. Jednak częściej używa się kombinacji backportów AndroidX (Activity Result API, NotificationCompat) i sprawdzeń w czasie wykonania, aby zachować niskie minSdk.

Strategia wyboru krok po kroku

Krok 1: otwórz Android Studio, File → New Project i sprawdź zalecane minSdk w kreatorze. Krok 2: sprawdź Distribution Dashboard w Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Krok 3: przeanalizuj zależności projektu — wykonaj budowanie i napraw konflikty manifest merger. Krok 4: oceń, które API poziomu X są rzeczywiście używane bez backportów. Krok 5: ustaw minSdk jako minimalną wartość pokrywającą 90%+ docelowej grupy odbiorców i kompatybilną ze wszystkimi zależnościami.

Zasięg urządzeń: dystrybucja poziomów API (2026)

Dystrybucja urządzeń według poziomu API — dynamiczny wskaźnik, który zmienia się co kwartał. Według Android Studio Distribution Dashboard na czerwiec 2026 roku, około 85% aktywnych urządzeń z Androidem działa na API 26 (Android 8.0) i wyższym, 72% — na API 29 (Android 10) i wyższym, 55% — na API 31 (Android 12) i wyższym. Rynek chiński ma własną statystykę ze względu na brak Google Play Services na wielu urządzeniach Huawei.

Urządzenia GMS (Google Mobile Services) aktualizują się szybciej: udział API 31+ na nich sięga 68% dzięki obowiązkowym wymaganiom Google Play wobec producentów. Urządzenia non-GMS (Huawei, Honor, niektóre chińskie marki) mają starszy rozkład: udział API 31+ na nich wynosi około 35%. Jeśli aplikacja jest przeznaczona na rynek międzynarodowy, opieraj się na globalnych statystykach. Jeśli na chiński — uwzględniaj segment non-GMS.

Wniosek: dla międzynarodowej aplikacji minSdk 26 pokrywa 85% urządzeń przy minimalnych kosztach kompatybilności wstecznej. Dla aplikacji z odbiorcami w rozwijających się regionach minSdk 21 (97% zasięgu) jest uzasadnione, ale będzie wymagać więcej kodu do pracy z przestarzałymi API. Dla aplikacji Enterprise z kontrolowaną flotą urządzeń można ustawić minSdk 31 i całkowicie pozbyć się kodu fallback.

Kompatybilność wsteczna: AndroidX, lint i @RequiresApi

Kompatybilność wsteczna — główna trudność przy niskim minSdkVersion. AndroidX (dawniej Support Library) dostarcza backporty nowoczesnych API na stare wersje Androida: AppCompatActivity dla Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat i dziesiątki innych komponentów. Używanie odpowiedników AndroidX zamiast natywnych API — pierwszy krok do kompatybilności.

lint (statyczny analizator Android Studio) skanuje kod w poszukiwaniu wywołań API powyżej minSdkVersion. Jeśli metoda jest oznaczona @RequiresApi z poziomem API wyższym niż minSdk i wywołana bez sprawdzenia, lint podświetla błąd. Aby stłumić ostrzeżenie, użyj adnotacji @SuppressLint("NewApi") na metodzie lub @RequiresApi(Build.VERSION_CODES.TIRAMISU) na całej funkcji. Sprawdzenia w czasie wykonania przez Build.VERSION.SDK_INT — podstawowy mechanizm bezpiecznego wywoływania nowych API na starych urządzeniach.

// Przykład kompatybilności wstecznej: PhotoPicker (API 34+) i 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) — działa na każdym poziomie API
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker dostępny tylko od API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Używamy PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (działa na wszystkich wersjach)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Tej metody nie można wywoływać na API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Klasa ImagePickerActivity demonstruje trzy poziomy kompatybilności wstecznej. Activity Result API z AndroidX działa na wszystkich poziomach API, więc dla podstawowego wyboru obrazu minSdk nie ma znaczenia. PhotoPicker (ACTION_PICK_IMAGES) jest dostępny tylko od API 34 i wywoływany pod sprawdzeniem SDK_INT z fallbackiem na GetContent. Metoda usePhotoPickerOnly jest oznaczona @RequiresApi — lint nie pozwoli jej wywołać bez sprawdzenia. AppCompat z AndroidX automatycznie dostosowuje motyw, fragmenty i animacje do wersji systemu.

minSdkVersion w bibliotekach i modułach

Biblioteki (AAR, JAR) również mają minSdkVersion określony w swoim manifeście. Przy podłączaniu biblioteki Gradle sprawdza kompatybilność: jeśli minSdk biblioteki jest wyższe niż minSdk aplikacji, budowanie kończy się błędem. Dla publicznych bibliotek zaleca się określenie minimalnego możliwego minSdk (21 w większości przypadków), aby nie ograniczać konsumentów. Jeśli biblioteka wymaga API 29+, traci ~28% potencjalnych użytkowników.

Projekty wielomodułowe mogą mieć różne minSdkVersion dla różnych modułów. Na przykład moduł :core:network może mieć minSdk 26, a moduł :feature:camera — minSdk 29 (z powodu CameraX z określonymi wymaganiami). Google Play wymaga, aby minSdk głównego modułu :app był niższy lub równy minSdk wszystkich zależnych modułów. W praktyce wszystkie moduły jednej aplikacji mają zwykle ten sam minSdk dla uproszczenia utrzymania.

// build.gradle.kts — moduł biblioteczny z niskim minSdk
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Minimalny dla maksymalnego zasięgu
        targetSdk = 36
    }
}

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

Moduł biblioteczny z minSdk = 21 jest kompatybilny z 97% urządzeń i nie ogranicza konsumentów. Jeśli biblioteka używa API powyżej 21, programista musi dodać sprawdzenia w czasie wykonania lub wskazać @RequiresApi na odpowiednich metodach. AndroidX Core KTX (minSdk 21) dostarcza backporty dla Context, Bundle, Locale i innych klas systemowych, pozwalając bibliotece zachować niski minSdk.

Typowe błędy przy wyborze minSdkVersion

Błędy przy wyborze minSdk mogą kosztować tysiące instalacji lub tygodnie dodatkowego programowania. Pierwszy typowy błąd — kopiowanie minSdk z szablonu projektu bez analizy Distribution Dashboard. Wielu programistów zostawia minSdk = 21 z szablonu Android Studio, choć dla ich odbiorców minSdk 26 byłby wystarczający i zmniejszyłby liczbę sprawdzeń SDK_INT w kodzie.

Drugi błąd — zbyt wysokie minSdk bez uwzględnienia rynku. Jeśli ustawisz minSdk = 31 (Android 12) dla międzynarodowej aplikacji, tracisz ~45% urządzeń. Dla startupu lub aplikacji z masową publicznością to katastrofa. Zawsze sprawdzaj Distribution Dashboard przed podniesieniem minSdk i używaj testów A/B w Google Play Console, jeśli nie jesteś pewien.

Trzeci błąd — ignorowanie minSdk zależności. Przy dodawaniu nowej biblioteki sprawdzaj jej minSdk w dokumentacji lub pliku POM. Firebase ML Kit wymaga minSdk 21, niektóre niestandardowe biblioteki do kamery wymagają minSdk 29. Jeśli manifest merger ulegnie awarii w produkcji z powodu nowej biblioteki, naprawa może zająć dni.

// Przykład: sprawdzanie kompatybilności API w czasie wykonania
fun checkFeatureAvailability(): Boolean {
    // Typowy błąd — wywołanie API bez sprawdzenia SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — używamy PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — używamy MediaStore
            true
        }
        else -> {
            // API < 29 — używamy ACTION_GET_CONTENT
            true
        }
    }
}

Prawidłowa architektura sprawdzeń poziomu API — when z zakresami pokrywającymi wszystkie możliwe wartości od minSdk do compileSdk. Kluczowa zasada: każde wywołanie API poziomu X musi być chronione sprawdzeniem VERSION.SDK_INT dla wszystkich urządzeń z poziomem API od minSdk do X. lint pomaga wykryć niesprawdzone wywołania, ale nie może zagwarantować pełnego pokrycia dla dynamicznego kodu.