Понимание Android API уровней и как выбрать min/target/compile SDK

API level — числовая метка версии Android. Коротко: minSdk определяет, на каких устройствах приложение установится; targetSdk говорит системе, к каким поведенческим изменениям приложение готово; compileSdk указывает, с какими API вы компилируете код (compileSdk >= targetSdk). Практическое правило 2026: minSdk — по аудитории/зависимостям (обычно >=21), targetSdk — последний требуемый Google Play или последний стабильный, compileSdk — не ниже targetSdk.

Что такое API level и зачем он нужен

API level — целое число, которое однозначно идентифицирует набор платформенных API (классы, манифест‑атрибуты, разрешения и т.д.). Система и магазин используют его для проверки совместимости и применения поведенческих изменений к приложениям. В Gradle это задают как minSdk, targetSdk и compileSdk.

minSdk, targetSdk, compileSdk — по делу

• minSdk — минимальный поддерживаемый уровень: ниже него приложение не установится. Выбирайте исходя из статистики пользователей и требований библиотек.
• targetSdk — уровень, для которого приложение оптимизировано; при совпадении/превышении система применяет новые поведенческие правила. Play Console может требовать минимум targetSdk для загрузки.
• compileSdk — SDK, с которым вы компилируете проект; даёт доступ к сигнатурам API во время компиляции. Обычно ставят последний стабильный SDK.

Пример конфигурации (Gradle Kotlin DSL):

android {
    compileSdk = 36
    defaultConfig {
        minSdk = 21
        targetSdk = 35
    }
}

Как выбрать значения и безопасно поднять их — пошагово

1. Соберите данные: статистика устройств из Play Console или аналитики продукта.
2. Проверьте зависимости: многие библиотеки требуют minSdk ≥ 21. Убедитесь, что ключевые библиотеки поддерживают выбранный minSdk.
3. Выберите minSdk по компромиссу «охват ↔ стоимость поддержки». Если пользователи ниже порога составляют <1–2%, поднимайте minSdk.
4. Выберите targetSdk: ориентируйтесь на последний стабильный или требование Play. Планируйте обновление поэтапно (например, 33 → 34 → 35).
5. Перед изменением target: установите compileSdk ≥ targetSdk, обновите зависимости и AGP, соберите проект и исправьте ошибки.
6. Тестируйте: на minSdk, на нескольких промежуточных версиях и на целевом уровне. Проверьте permissions, background‑work, уведомления, файловую систему и нативные либы.
7. Выпустите в staged rollout, мониторьте краши и метрики.

Чек‑лист при поднятии SDK

• Обновить compileSdk = targetSdk.
• Обновить Android Gradle Plugin и зависимости.
• Прогнать lint, исправить предупреждения.
• Прогнать unit/integration/UI тесты на ключевых API‑уровнях.
• Загружать в Play через staged rollout и смотреть отчёты.

Частые ошибки

• Подняли target без обновления compileSdk → ошибки компиляции.
• Не протестировали на старых версиях → runtime crashes.
• Использование maxSdkVersion в манифесте — блокирует установку на будущих устройствах.
• Полагание на устаревшие библиотеки, которые внезапно повышают minSdk.

FAQ

• Нужно ли всегда ставить targetSdk = latest?
  Да, если вы готовы провести тестирование и исправить поведенческие изменения. В противном случае следуйте требованию Play и планируйте постепенный переход.
• Можно ли компилировать с compileSdk ниже targetSdk?
  Нет — это приведёт к отсутствию API при компиляции; всегда compileSdk ≥ targetSdk.
• Как поддерживать старые устройства без существенных затрат?
  Используйте AndroidX/Jetpack, проверяйте Build.VERSION.SDK_INT перед использованием новых API и обеспечьте graceful fallback.

Заключение: правильно выбранные minSdk/targetSdk/compileSdk — это баланс охвата устройств и возможности использовать новые Android‑фичи. Планируйте обновления, тестируйте поэтапно и следите за требованиями Play. Если хотите, могу проверить ваш Gradle‑файл и предложить конкретный план обновления.