minSdkVersion: какво е това, как да изберете минималната версия на Android

Какво е minSdkVersion в Android?

minSdkVersion — целочислен параметър в build.gradle, който задава минималното API ниво на Android за инсталиране на приложение. Ако API нивото на устройството е под посочената стойност, PackageManager блокира инсталацията, а Google Play Store скрива приложението от резултатите от търсенето за такова устройство. minSdkVersion се записва в AndroidManifest.xml на етапа на изграждане чрез тага <uses-sdk android:minSdkVersion> и се проверява при всяка инсталация.

Стойността на minSdkVersion е компромис между обхвата на аудиторията и достъпа до нови API. Колкото по-ниско е minSdk, толкова повече устройства могат да инсталират приложението, особено в развиващите се региони, където старите Android смартфони са популярни. Колкото по-високо е minSdk, толкова по-малко код за обратна съвместимост е необходим и толкова повече съвременни API са достъпни без проверки по време на изпълнение. Android Jetpack и библиотеките AndroidX предоставят backport на много нови API към стари версии на Android, което позволява избор на по-ниско minSdk без загуба на функционалност.

minSdkVersion влияе на всички етапи на разработка: статичен анализ (lint използва minSdk за предупреждения), съвместимост на зависимостите (библиотеките може да изискват собствено minSdk), тестване (трябва да се тества на устройства с minSdk) и Google Play Console (обхватът на аудиторията се изчислява на базата на minSdk). Промяната на minSdkVersion е едно от най-отговорните решения в конфигурацията на проекта, тъй като засяга кода, тестовете и потребителската база.

Къде се посочва minSdkVersion

Build.gradle.kts (Kotlin DSL) — модерният стандарт в Android проектите. Параметърът minSdk се задава в блока defaultConfig на ниво модул. Стойността може да бъде презаписана за различни типове изграждане и продуктови варианти, което позволява тестване на по-ниски API без промяна на основната стойност.

// build.gradle.kts — основна конфигурация на 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"
    }

    // Презаписване на minSdk за различни flavor
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

В примера minSdk = 26 съответства на Android 8.0 Oreo. Това е популярна стойност през 2026 г.: според Android Studio Distribution Dashboard отрязва само ~15% от устройствата. compileSdk = 36 предоставя достъп до всички API на Android 16, а targetSdk = 36 активира поведенческите промени на най-новата версия. За debug изграждания minSdk може да бъде намален за тестване на стари емулатори.

Как да изберете minSdkVersion: фактори и стратегия

Изборът на minSdkVersion — стратегическо решение, основано на анализ на целевата аудитория, изискванията към API и екосистемата от библиотеки. Няма единна правилна стойност за всички проекти. През 2026 г. Android Studio препоръчва minSdk = 26 (Android 8.0) като базово ниво за нови проекти, но за B2B приложения или корпоративни решения са приемливи по-ниски или по-високи стойности.

Фактори за избор на minSdkVersion

Първи фактор — Distribution Dashboard. Android Studio предоставя статистика на активните устройства по API ниво въз основа на данни от Google Play, актуализирана месечно. minSdkVersion трябва да покрива поне 90-95% от активните устройства на целевия пазар. За международни приложения с аудитория в Африка и Югоизточна Азия minSdk трябва да бъде намален до 21 (Android 5.0) поради високия дял на стари устройства.

Втори фактор — изисквания на зависимостите. Всяка библиотека има собствено minSdkVersion, посочено в нейния манифест. Ако библиотека изисква minSdk 29, а приложението — minSdk 26, изграждането ще завърши с грешка manifest merger. Модерните библиотеки на Google Play Services имат minSdk 21, Firebase — minSdk 21, повечето Jetpack библиотеки — minSdk 21 или 26, Compose BOM — minSdk 21. За Compose минималният праг — API 21.

Трети фактор — необходими API. Ако ключова функционалност на приложението изисква API, достъпно само от определено ниво (напр. PhotoPicker — API 34, Predicted Navigation — API 35), това може да оправдае повишаването на minSdk. По-често обаче се използва комбинация от AndroidX backport (Activity Result API, NotificationCompat) и проверки по време на изпълнение, за да се запази ниско minSdk.

Поетапна стратегия за избор

Стъпка 1: отворете Android Studio, File → New Project и вижте препоръчаното minSdk в съветника. Стъпка 2: проверете Distribution Dashboard в Android Studio (View → Tool Windows → App Inspection → Distribution Dashboard). Стъпка 3: анализирайте зависимостите на проекта — изпълнете изграждане и поправете конфликтите manifest merger. Стъпка 4: преценете кои API на ниво X реално се използват без backport. Стъпка 5: задайте minSdk като минималната стойност, покриваща 90%+ от целевата аудитория и съвместима с всички зависимости.

Обхват на устройства: разпределение на API нивата (2026)

Разпределение на устройствата по API ниво — динамичен показател, който се променя всяко тримесечие. Според Android Studio Distribution Dashboard за юни 2026 г., около 85% от активните Android устройства работят на API 26 (Android 8.0) и по-високи, 72% — на API 29 (Android 10) и по-високи, 55% — на API 31 (Android 12) и по-високи. Китайският пазар има своя статистика поради липсата на Google Play Services на много устройства Huawei.

GMS устройства (Google Mobile Services) се актуализират по-бързо: делът на API 31+ при тях достига 68% благодарение на задължителните изисквания на Google Play към производителите. Не-GMS устройства (Huawei, Honor, някои китайски марки) имат по-старо разпределение: делът на API 31+ при тях е около 35%. Ако приложението е насочено към международния пазар, разчитайте на глобалната статистика. Ако към китайския — вземете предвид не-GMS сегмента.

Заключение: за международно приложение minSdk 26 покрива 85% от устройствата с минимални разходи за обратна съвместимост. За приложения с аудитория в развиващи се региони minSdk 21 (97% обхват) е оправдано, но ще изисква повече код за работа със остарели API. За Enterprise приложения с контролиран парк от устройства можете да зададете minSdk 31 и напълно да се отървете от fallback код.

Обратна съвместимост: AndroidX, lint и @RequiresApi

Обратна съвместимост — основната трудност при ниско minSdkVersion. AndroidX (преди Support Library) предоставя backport на съвременни API към стари версии на Android: AppCompatActivity за Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat и десетки други компоненти. Използването на AndroidX еквиваленти вместо нативни API — първата стъпка към съвместимост.

lint (статичен анализатор на Android Studio) сканира кода за извиквания на API над minSdkVersion. Ако метод е маркиран с @RequiresApi с API ниво над minSdk и бъде извикан без проверка, lint откроява грешката. За потискане на предупреждението използвайте анотация @SuppressLint("NewApi") на метода или @RequiresApi(Build.VERSION_CODES.TIRAMISU) на цялата функция. Проверки по време на изпълнение чрез Build.VERSION.SDK_INT — основният механизъм за безопасно извикване на нови API на стари устройства.

// Пример за обратна съвместимост: PhotoPicker (API 34+) и 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) — работи на всяко API ниво
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker достъпен само от API 34
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // Използваме PhotoPicker (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (работи на всички версии)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Този метод не може да бъде извикан на API < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

Класът ImagePickerActivity демонстрира три нива на обратна съвместимост. Activity Result API от AndroidX работи на всички API нива, така че за основен избор на изображение minSdk няма значение. PhotoPicker (ACTION_PICK_IMAGES) е достъпен само от API 34 и се извиква под проверка SDK_INT с fallback към GetContent. Методът usePhotoPickerOnly е маркиран с @RequiresApi — lint няма да позволи извикването му без проверка. AppCompat от AndroidX автоматично адаптира темата, фрагментите и анимациите към версията на операционната система.

minSdkVersion в библиотеки и модули

Библиотеки (AAR, JAR) също имат minSdkVersion, посочен в техния манифест. При свързване на библиотека Gradle проверява съвместимостта: ако minSdk на библиотеката е по-високо от minSdk на приложението, изграждането се проваля с грешка. За публични библиотеки се препоръчва посочване на възможно най-ниското minSdk (21 в повечето случаи), за да не се ограничават потребителите. Ако библиотека изисква API 29+, тя губи ~28% от потенциалните потребители.

Многомодулни проекти могат да имат различни minSdkVersion за различни модули. Например, модулът :core:network може да има minSdk 26, а модулът :feature:camera — minSdk 29 (поради CameraX с определени изисквания). Google Play изисква minSdk на основния модул :app да бъде по-ниско или равно на minSdk на всички зависими модули. На практика всички модули на едно приложение обикновено имат еднакво minSdk за опростяване на поддръжката.

// build.gradle.kts — библиотечен модул с ниско minSdk
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Минимално за максимален обхват
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, добавя backport
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Библиотечен модул с minSdk = 21 е съвместим с 97% от устройствата и не ограничава потребителите. Ако библиотеката използва API над 21, разработчикът трябва да добави проверки по време на изпълнение или да посочи @RequiresApi на съответните методи. AndroidX Core KTX (minSdk 21) предоставя backport за Context, Bundle, Locale и други системни класове, позволявайки на библиотеката да запази ниско minSdk.

Типични грешки при избора на minSdkVersion

Грешки при избора на minSdk могат да струват хиляди инсталации или седмици допълнителна разработка. Първата типична грешка — копиране на minSdk от шаблона на проекта без анализ на Distribution Dashboard. Много разработчици оставят minSdk = 21 от шаблона на Android Studio, въпреки че за тяхната аудитория minSdk 26 би бил достатъчен и би намалил броя на проверките SDK_INT в кода.

Втората грешка — твърде високо minSdk без отчитане на пазара. Ако зададете minSdk = 31 (Android 12) за международно приложение, губите ~45% от устройствата. За стартъп или приложение с масова аудитория това е катастрофа. Винаги проверявайте Distribution Dashboard преди повишаване на minSdk и използвайте A/B тестване в Google Play Console, ако не сте сигурни.

Третата грешка — игнориране на minSdk на зависимостите. При добавяне на нова библиотека проверявайте нейното minSdk в документацията или POM файла. Firebase ML Kit изисква minSdk 21, някои персонализирани библиотеки за камера изискват minSdk 29. Ако manifest merger се провали в производствена среда поради нова библиотека, поправката може да отнеме дни.

// Пример: проверка на съвместимостта на API по време на изпълнение
fun checkFeatureAvailability(): Boolean {
    // Типична грешка — извикване на API без проверка SDK_INT
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — използваме PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — използваме MediaStore
            true
        }
        else -> {
            // API < 29 — используем ACTION_GET_CONTENT
            true
        }
    }
}

Правилната архитектура за проверки на API ниво — when с диапазони, покриващи всички възможни стойности от minSdk до compileSdk. Ключовото правило: всяко извикване на API от ниво X трябва да бъде защитено с проверка VERSION.SDK_INT за всички устройства с API ниво от minSdk до X. lint помага за откриване на непроверени извиквания, но не може да гарантира пълно покритие за динамичен код.