minSdkVersion: що це та як вибрати мінімальну версію Android

Що таке minSdkVersion в Android?

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

Значення minSdkVersion — компроміс між охопленням аудиторії та доступом до нових API. Чим нижчий minSdk, тим більше пристроїв може встановити додаток, особливо в регіонах, що розвиваються, де популярні старі Android-смартфони. Чим вищий minSdk, тим менше коду зворотної сумісності потрібно і тим більше сучасних API доступно без runtime-перевірок. Android Jetpack та бібліотеки AndroidX надають бекпорти багатьох нових API на старі версії Android, що дозволяє вибирати нижчий minSdk без втрати функціональності.

minSdkVersion впливає на всі етапи розробки: статичний аналіз (lint використовує minSdk для попереджень), сумісність залежностей (бібліотеки можуть вимагати свій minSdk), тестування (необхідно тестувати на пристроях з minSdk) та Google Play Console (охоплення аудиторії розраховується на основі minSdk). Зміна minSdkVersion — одне з найвідповідальніших рішень у налаштуванні проєкту, оскільки воно зачіпає код, тести та користувацьку базу.

Де вказується minSdkVersion

Build.gradle.kts (Kotlin DSL) — сучасний стандарт в Android-проєктах. Параметр minSdk задається в блоці defaultConfig на рівні модуля. Значення може перевизначатися для різних build types та product flavors, що дозволяє тестувати на нижчих 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 році: воно відсікає лише ~15% пристроїв згідно з Android Studio Distribution Dashboard. compileSdk = 36 дає доступ до всіх API Android 16, а targetSdk = 36 включає behavioural changes останньої версії. Для debug-збірок minSdk можна знизити для тестування на старих емуляторах.

Як вибрати minSdkVersion: фактори та стратегія

Вибір minSdkVersion — стратегічне рішення, засноване на аналізі цільової аудиторії, вимог до API та екосистеми бібліотек. Не існує єдиного правильного значення для всіх проєктів. У 2026 році Android Studio рекомендує minSdk = 26 (Android 8.0) як базовий рівень для нових проєктів, але для B2B-додатків або корпоративних рішень допустимі нижчі або вищі значення.

Фактори вибору minSdkVersion

Перший фактор — Distribution Dashboard. Android Studio надає статистику активних пристроїв за API Level на основі даних 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-бекпортів (Activity Result API, NotificationCompat) та runtime-перевірок, щоб зберегти низький 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 реально використовуються без бекпортів. Крок 5: встановіть minSdk як мінімальне значення, що покриває 90%+ цільової аудиторії та сумісне з усіма залежностями.

Охоплення пристроїв: розподіл API Level (2026)

Розподіл пристроїв за API Level — динамічний показник, який змінюється щокварталу. За даними 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 до виробників. Non-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) надає бекпорти сучасних API на старі версії Android: AppCompatActivity для Material Design, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat та десятки інших компонентів. Використання AndroidX-еквівалентів замість нативних API — перший крок до сумісності.

lint (статичний аналізатор Android Studio) сканує код на виклики API вище minSdkVersion. Якщо метод позначений @RequiresApi з API Level вище minSdk і викликаний без перевірки, lint підсвічує помилку. Для придушення попередження використовуйте анотацію @SuppressLint("NewApi") на методі або @RequiresApi(Build.VERSION_CODES.TIRAMISU) на всю функцію. Runtime-перевірки через 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 Level
    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 Level, тому для базового вибору зображення 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% потенційних користувачів.

Multi-module проєкти можуть мати різні 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, додає бекпорти
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

Бібліотечний модуль з minSdk = 21 сумісний з 97% пристроїв і не обмежує споживачів. Якщо бібліотека використовує API вище 21, розробник повинен додати runtime-перевірки або вказати @RequiresApi на відповідних методах. AndroidX Core KTX (minSdk 21) надає бекпорти для Context, Bundle, Locale та інших системних класів, дозволяючи бібліотеці зберігати низький minSdk.

Типові помилки при виборі minSdkVersion

Помилки при виборі minSdk можуть коштувати тисяч встановлень або тижнів додаткової розробки. Перша типова помилка — копіювання minSdk з шаблону проєкту без аналізу Distribution Dashboard. Багато розробників залишають minSdk = 21 з Android Studio Template, хоча для їхньої аудиторії 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 впаде в production через нову бібліотеку, виправлення може зайняти дні.

// Приклад: перевірка сумісності API в runtime
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 Level — when з діапазонами, що покривають всі можливі значення від minSdk до compileSdk. Ключове правило: будь-який виклик API рівня X повинен бути захищений перевіркою VERSION.SDK_INT для всіх пристроїв з API Level від minSdk до X. lint допомагає виявити неперевірені виклики, але не може гарантувати повне покриття для динамічного коду.