API Level: что это такое, версии API и targetSdk

Что такое API Level Android?

API Level Android — целочисленный идентификатор (integer), который присваивается каждому публичному релизу Android Framework API. Первый релиз Android 1.0 имел API Level 1, Android 1.5 — API Level 3, Android 2.2 — API Level 8, Android 4.0 — API Level 14, Android 8.0 — API Level 26, Android 12 — API Level 31, Android 14 — API Level 34, Android 15 — API Level 35, Android 16 (2025) — API Level 36. Каждый новый API Level может добавлять новые классы, методы, константы, разрешения и изменять поведение существующих.

API Level не увеличивается строго на 1 с каждым релизом. Например, Android 4.4W (Wear) имеет API 20, а Android 5.0 — API 21. Пропуски связаны с внутренними итерациями и устройствами Wear OS. Разработчику важно знать не имя версии (KitKat, Lollipop, Tiramisu), а её API Level — именно он используется в коде для проверок совместимости.

Ключевое назначение API Level — обратная совместимость. Приложение, скомпилированное против API 34, может работать на устройствах с API 34 и ниже (если не использует новые API без проверки). Android Runtime (ART) проверяет вызовы API на уровне системы и применяет behavioural changes в зависимости от targetSdkVersion приложения.

Как Android обрабатывает API Level

При установке приложения PackageManager проверяет, что API Level устройства >= minSdkVersion из AndroidManifest.xml. Если условие не выполнено — установка блокируется с сообщением "App not installed". Во время работы Android Runtime отслеживает вызовы API, которые требуют более высокого API Level, и генерирует NoSuchMethodError или UnsatisfiedLinkError, если метод отсутствует в текущей версии.

minSdk, targetSdk, compileSdk: различия и роль каждого параметра

В файле build.gradle (Module: app) разработчик указывает три параметра API Level: minSdkVersion, targetSdkVersion и compileSdkVersion. Их путаница — одна из самых частых ошибок начинающих Android-разработчиков. Каждый параметр отвечает за разный аспект совместимости, и их значения должны быть согласованы.

minSdkVersion

minSdkVersion — минимальный API Level, на котором приложение может быть установлено и запущено. Устройства с API Level ниже minSdk не видят приложение в Google Play и не могут его установить. Значение выбирается на основе целевой аудитории: minSdk 21 (Android 5.0) покрывает 97% устройств, minSdk 26 (Android 8.0) — около 85%, minSdk 31 (Android 12) — около 55% (данные Android Studio Distribution Dashboard, 2026). Чем ниже minSdk, тем больше охват, но тем больше кода для обратной совместимости.

targetSdkVersion

targetSdkVersion — API Level, на котором приложение протестировано. Android использует targetSdk для применения behavioural changes: если приложение указывает targetSdk 33, система включает все поведенческие изменения, введённые в API 33. Если targetSdk 31, система не применяет изменения API 32-33, сохраняя совместимость со старым поведением. Это самый важный параметр для безопасности: Google Play требует targetSdk не старше 1 года от текущего API Level.

compileSdkVersion

compileSdkVersion — версия Android SDK, против которой компилируется код. Определяет, какие API доступны во время компиляции. compileSdk должна быть >= targetSdk и, желательно, равна последнему стабильному API Level. Повышение compileSdk не влияет на рантайм-поведение — только на доступность новых API для компилятора. После повышения compileSdk нужно проверить код на использование deprecated API и новые требования к permissions.

// build.gradle.kts — пример настройки API Level
plugins {
    id("com.android.application") version "8.7.0"
    id("org.jetbrains.kotlin.android") version "2.1.0"
}

android {
    namespace = "com.example.myapp"
    compileSdk = 36  // Android 16

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26      // Android 8.0
        targetSdk = 36    // Android 16
        versionCode = 1
        versionName = "1.0.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
}

В примере build.gradle.kts compileSdk = 36 (последний на момент написания), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 даёт доступ ко всем API Android 16. targetSdk 36 включает все behavioural changes Android 16. minSdk 26 покрывает ~85% устройств. AndroidX Activity KTX и AppCompat обеспечивают обратную совместимость для фрагментов и тем.

AndroidManifest.xml

Параметры minSdk и targetSdk также можно указать в AndroidManifest.xml, но современные проекты используют build.gradle — значения из Gradle перезаписывают манифест. В манифесте может быть полезно указать для библиотек и модулей, не использующих Gradle build config.

Behavioural Changes: как targetSdk влияет на поведение приложения

Behavioural changes (изменения поведения) — это модификации работы системы Android, которые применяются только к приложениям с targetSdk >= определённого API Level. Каждый новый релиз Android вводит behavioural changes, которые могут сломать существующие приложения, если они не обновлены. Это ключевой механизм безопасности Android: старые приложения продолжают работать как раньше, новые — следуют актуальным правилам.

Основные behavioural changes по версиям

Android 10 (API 29) — Scoped Storage: приложения с targetSdk 29+ не имеют прямого доступа к общей файловой системе, только через MediaStore, SAF или собственное хранилище. Android 11 (API 30) — Package Visibility: пакетный фильтр, приложения видят только установленные пакеты, с которыми взаимодействуют. Android 12 (API 31) — Foreground Service Notification: все foreground-сервисы обязаны показывать уведомление в течение 10 секунд после запуска. Android 13 (API 33) — POST_NOTIFICATIONS: runtime-разрешение для push-уведомлений. Android 14 (API 34) — Foreground Service Types: обязательная декларация типа foreground-сервиса в манифесте.

// Обработка behavioural changes Android 13 (API 33): POST_NOTIFICATIONS
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.core.content.ContextCompat

class NotificationHelper {

    fun requestNotificationPermission(activity: MainActivity) {
        // Разрешение POST_NOTIFICATIONS работает только с API 33+
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // Ниже API 33 разрешение не требуется
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // Разрешение уже выдано, можно отправлять уведомления
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // Показать объяснение, зачем нужно разрешение
                activity.showRationale()
            }

            else -> {
                // Запросить разрешение
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Создание и отображение уведомления
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Уведомление")
            .setContentText("Новое сообщение")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Регистрация requestPermissionLauncher в Activity
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // Разрешение получено
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Пример обработки POST_NOTIFICATIONS на Kotlin: проверка Build.VERSION.SDK_INT >= TIRAMISU, запрос runtime-разрешения через ActivityResultContracts.RequestPermission, обработка результата в колбэке. Без этого разрешения приложение с targetSdk 33+ не может показывать push-уведомления. Ниже API 33 разрешение не требуется — код проверки предотвращает вызов unavailable API.

Scoped Storage (Android 10+)

Scoped Storage — одно из самых значительных behavioural changes. Начиная с API 29 (targetSdk 29+), приложение не может получить прямой File-доступ к директориям Pictures, Downloads, Music и Documents. Вместо этого используется MediaStore для мультимедиа, SAF (Storage Access Framework) для произвольных файлов и getExternalFilesDir() для собственного хранилища. Исключение — приложения с разрешением MANAGE_EXTERNAL_STORAGE, которое требует одобрения Google Play.

Требования Google Play к API Level и targetSdk

Google Play устанавливает обязательные требования к targetSdkVersion для публикации приложений. С августа 2024 года Google Play требует targetSdkVersion >= API 33 (Android 13). Каждый год порог повышается: новые приложения и обновления должны указывать targetSdk не старше 1 года от текущего мажорного API Level. Нарушение требования ведёт к блокировке публикации и удалению приложения из магазина.

Почему Google Play ужесточает требования

Основная причина — безопасность. Каждый новый Android API Level вводит behavioural changes, закрывающие векторы атак: Scoped Storage (API 29) предотвращает кражу файлов, POST_NOTIFICATIONS (API 33) защищает от спам-уведомлений, Foreground Service Types (API 34) ограничивает скрытые фоновые сервисы. Приложения с низким targetSdk не получают эти защиты и становятся угрозой для пользователей. Google Play не может допускать устаревшие приложения на современные устройства.

Проверка соответствия требованиям

Google Play Console проверяет targetSdkVersion при загрузке APK/AAB. Если targetSdk ниже требуемого — консоль блокирует публикацию с сообщением: "Your app currently targets API level X and must target at least API level Y". Разработчик должен обновить build.gradle, перекомпилировать приложение, протестировать behavioural changes и повторно загрузить. AAB-формат рекомендован для всех новых публикаций (с августа 2021 года обязателен).

Проверка API Level в коде: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT — статическая целочисленная константа, содержащая API Level устройства, на котором запущено приложение. Это основной инструмент для runtime-проверок версии Android. Build.VERSION_CODES содержит именованные константы для каждого API Level: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). Сравнение через if (SDK_INT >= VERSION_CODES.TIRAMISU) — стандартный паттерн.

// Примеры проверки API Level в коде Android
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Базовая проверка API Level
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Адаптивный вызов API с проверкой
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable доступен только с API 26 (Android 8)
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // fallback для старых устройств
    }

    // 3. Проверка разрешения POST_NOTIFICATIONS (только API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. Выбор провайдера изображений по API Level
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ использует PhotoPicker
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ использует Intent ACTION_OPEN_DOCUMENT
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (все версии)
                "get_content"
            }
        }
    }

    // 5. Java-style проверка через @TargetApi (для обратной совместимости)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Scoped Storage поведение зависит от targetSdk, а не от SDK_INT
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Информация о сборке для аналитики
    fun getDeviceApiInfo(): Map<String, Any> {
        return mapOf(
            "sdk_int" to VERSION.SDK_INT,
            "release" to VERSION.RELEASE,
            "codename" to VERSION.CODENAME,
            "incremental" to VERSION.INCREMENTAL,
            "preview_sdk" to VERSION.PREVIEW_SDK_INT
        )
    }
}

// Тестирование
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

Класс ApiLevelHelper демонстрирует все основные паттерны проверки API Level: isAtLeastTiramisu с SDK_INT >= VERSION_CODES, getAdaptiveIcon с fallback для старых версий, getImagePickerProvider с when-мультиветвлением, getDeviceApiInfo для аналитики. Ключевое правило — не вызывать новые API без проверки SDK_INT, иначе приложение упадёт с NoSuchMethodError на старых устройствах.

ANT (Android New API) и lint

Android Studio включает статический анализатор lint, который предупреждает об использовании API выше minSdkVersion. Если метод вызван без проверки SDK_INT, lint подсвечивает ошибкой: "Call requires API level 34 (current min is 26)". Решения: добавить @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) на метод или if-проверку SDK_INT. @TargetApi — устаревшая аннотация, рекомендуется @RequiresApi.

Таблица соответствия API Level и версий Android

Таблица API Level — справочный инструмент для разработчика. Зная API Level устройства, можно определить версию Android и доступные функции. В таблице приведены все основные релизы Android с API Level 1 (2008) до API Level 36 (2025). Кодовые имена (Cupcake, Donut, Tiramisu, VanillaIceCream) используются внутри Google и в VERSION_CODES.

Таблица: пороговые API Level для behavioural changes

Следующая таблица показывает ключевые API Level, вводящие behavioural changes, которые ломают обратную совместимость при повышении targetSdk: