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 на системно ниво и прилага поведенчески промени в зависимост от 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 за прилагане на поведенчески промени: ако приложението задава 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 трябва да проверите кода за остарели 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 активира всички поведенчески промени на Android 16. minSdk 26 покрива ~85% от устройствата. AndroidX Activity KTX и AppCompat осигуряват обратна съвместимост за фрагменти и теми.

AndroidManifest.xml

Параметрите minSdk и targetSdk могат също да бъдат зададени в AndroidManifest.xml, но съвременните проекти използват build.gradle — стойностите от Gradle презаписват манифеста. В манифеста може да е полезно да се зададе за библиотеки и модули, които не използват конфигурация за изграждане на Gradle.

Поведенчески промени: как targetSdk влияе на поведението на приложението

Поведенческите промени са модификации на начина на работа на системата Android, които се прилагат само за приложения с targetSdk >= определено API Level. Всяка нова версия на Android въвежда поведенчески промени, които могат да счупят съществуващи приложения, ако не бъдат актуализирани. Това е ключов механизъм за сигурност на Android: старите приложения продължават да работят както преди, новите следват актуалните правила.

Основни поведенчески промени по версии

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

// Обработка на поведенчески промени на 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, обработка на резултата в callback. Без това разрешение приложение с targetSdk 33+ не може да показва push известия. Под API 33 не се изисква разрешение — кодът за проверка предотвратява извикване на недостъпни API.

Scoped Storage (Android 10+)

Scoped Storage е една от най-значимите поведенчески промени. Започвайки от API 29 (targetSdk 29+), приложението не може да получи директен достъп до файлове в директориите 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 затяга изискванията

Основната причина е сигурността. Всяко ново API Level на Android въвежда поведенчески промени, които затварят вектори на атаки: 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, да прекомпилира приложението, да тества поведенческите промени и да качи отново. 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-стил проверка чрез @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 за поведенчески промени

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