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 помогает обнаружить непроверенные вызовы, но не может гарантировать полное покрытие для динамического кода.