API Level: що це таке, версії API та targetSdk

Що таке API Level Android?

API Level Android — цілочисельний ідентифікатор, який присвоюється кожному публічному релізу 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, система вмикає всі behavioural changes, введені в 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 та нові вимоги до дозволів.

// 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.

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: дозвіл під час виконання для 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, запит дозволу під час виконання через ActivityResultContracts.RequestPermission, обробка результату в колбеку. Без цього дозволу додаток з targetSdk 33+ не може показувати push-сповіщення. Нижче API 33 дозвіл не потрібен — код перевірки запобігає виклику недоступних 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 пристрою, на якому запущено додаток. Це основний інструмент для перевірок версії 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: