SDK Platform: какво е това, версии и Android SDK Manager

Какво е SDK Platform

SDK Platform — е основен компонент на Android SDK, представляващ пълен набор от библиотеки и инструменти за разработване на приложения под конкретна версия на Android. Всяка платформа се идентифицира чрез API Level — цяло число, което расте с излизането на нови версии на операционната система. Например Android 13 съответства на API Level 33, Android 14 — на API Level 34, Android 15 — на API Level 35.

За разлика от Android Studio (IDE), SDK Platform не съдържа редактор на код или дебъгер. Това е системен слой, който се свързва с компилатора и инструмента за изграждане. Когато разработчикът напише import android.app.Activity, компилаторът взема този клас от android.jar на конкретния SDK Platform. Без инсталирана платформа с необходимото API Level кодът няма да се компилира.

Google пуска нов SDK Platform за всяка стабилна версия на Android. Историята включва повече от 35 API Level — от Android 1.0 (API 1) до Android 15 (API 35). Всяка платформа е обратно съвместима: код, написан за API Level 21, ще работи на API Level 35, но не и обратното.

Защо е необходим отделен SDK Platform за всяка версия

Android се развива бързо: всяка версия добавя нови API, променя поведението на съществуващите и въвежда ограничения. Например Android 10 (API 29) въведе Scoped Storage, Android 12 (API 31) — SplashScreen API, Android 14 (API 34) — задължителни флагове за BroadcastReceiver. Разработчикът трябва да изгради приложението срещу текущата платформа, за да използва тези възможности.

В същото време приложението може да работи на стари версии на операционната система. За това в Gradle се посочва minSdk — минималното API Level, на което приложението работи. Кодът използва проверки на версията и условни извиквания на API. Този подход осигурява съвместимост без загуба на нови функции.

Състав на SDK Platform: основни компоненти

SDK Platform — не е един файл, а набор от компоненти, които заедно осигуряват компилирането, изграждането и тестването на приложението. Основният елемент е android.jar — архив с класовете на Android API, включени в тази версия. Този файл се свързва с компилатора Kotlin или Java и определя кои класове, методи и анотации са достъпни за разработчика.

Системни образи и емулатор

Всеки SDK Platform включва System Image — образ на операционната система за емулатора Android Virtual Device. Без съответния образ емулаторът няма да може да стартира виртуално устройство с необходимото API Level. System Images биват различни типове: Google APIs (с услуги на Google), Google Play (с Play Store) и AOSP (чист Android без услуги на Google).

Инструменти за изграждане и отстраняване на грешки

SDK Platform включва версия на Build-Tools и Platform-Tools, оптимизирана за това API Level. Build-Tools съдържат aapt2 (Android Asset Packaging Tool), dx/d8 (компилатор Dalvik/ART) и ApkSigner. Platform-Tools предоставят ADB (Android Debug Bridge), fastboot и SQLite. Тези инструменти се актуализират независимо от SDK Platform чрез SDK Manager.

Ресурси на платформата

Всяка платформа включва стандартни ресурси на Android — системни теми, стилове, анимации, цветове и размери. Тези ресурси се използват по време на компилиране: ако разработчикът се позовава на @android:style/Theme.Material.Light, инструментът за изграждане взема дефиницията от ресурсите на SDK Platform. Това гарантира еднакъв вид на системните компоненти на всички устройства.

API Level и версии на SDK Platform

API Level — е целочислен идентификатор на версията на Android SDK. Всяко издание на Android има едно API Level, което монотонно нараства. Разработчикът посочва API Level в три ключови параметъра на build.gradle: compileSdk, minSdk и targetSdk. Изборът на тези параметри определя кои API са достъпни и как системата обработва приложението.

Google препоръчва поддържането на minSdk на ниво не по-ниско от текущия праг на разпространение — според Android Studio Distribution Dashboard (2026), около 95% от устройствата работят на Android 8.0 (API 26) и по-високи. compileSdk трябва да бъде последният стабилен — това дава достъп до нови API и позволява на lint проверките да откриват остарели методи.

Еволюция на API Level: ключови промени

С всяко ново API Level Google въвежда значителни промени. Android 6.0 (API 23) добави runtime разрешения — приложението иска разрешения по време на работа, а не при инсталиране. Android 8.0 (API 26) въведе автоматично попълване на формуляри и канали за уведомления. Android 12 (API 31) коренно промени подхода към intent-овете — появиха се SplashScreen API и експортиране на компоненти чрез атрибута exported. Android 14 (API 34) направи задължително посочването на флагове за BroadcastReceiver и въведе строги ограничения за foreground services.

Разбирането на историята на API Level помага на разработчика да избере правилната стратегия за съвместимост. Ако приложението използва compileSdk 35, но minSdk 26, кодът може да извиква методи от API 35 само след проверка на версията чрез Build.VERSION.SDK_INT. Този подход се нарича version-gated development и е индустриален стандарт.

SDK Manager: инсталиране и настройка

SDK Manager — е инструмент за управление на компонентите на Android SDK: инсталиране на нови SDK Platform, актуализиране на съществуващи и премахване на остарели. SDK Manager е достъпен както като графичен интерфейс в Android Studio, така и като команден ред чрез sdkmanager. Чрез командния ред SDK Manager е удобен за използване в CI/CD пайплайнове, където няма графичен интерфейс.

SDK Manager инсталира платформи в директорията на Android SDK, която по подразбиране се намира в $HOME/Android/Sdk на Linux и macOS или %LOCALAPPDATA%\Android\Sdk на Windows. Вътре в директорията platforms има папки във формат android-{API Level}, всяка от които съдържа пълен SDK Platform.

Инсталиране на SDK Platform чрез sdkmanager

Командата sdkmanager приема идентификатор на пакет във формат "platforms;android-{API}". Например за инсталиране на SDK Platform 35 командата изглежда така:

# Инсталирай SDK Platform за API Level 35
sdkmanager "platforms;android-35"

# Инсталирай няколко платформи с една команда
sdkmanager "platforms;android-34" "platforms;android-33" "platforms;android-31"

# Списък на инсталираните платформи
sdkmanager --list_installed | grep platforms

# Премахни остарялата платформа
sdkmanager --uninstall "platforms;android-28"

Автоматично инсталиране чрез Gradle

Съвременните Android проекти използват Gradle Plugin, който може автоматично да инсталира SDK Platform при първото изграждане. За целта трябва да посочите compileSdk в build.gradle и да добавите SDK директорията в локалната конфигурация. Android Studio също предлага инсталиране на липсващата платформа при отваряне на проект — достатъчно е да натиснете бутона "Install SDK Platform" в прозореца за синхронизация на Gradle.

Важно е редовно да актуализирате SDK Platform чрез SDK Manager — заедно с платформата се актуализират Build-Tools и Platform-Tools, което влияе на производителността на изграждане и стабилността на отстраняване на грешки. Google препоръчва проверка на актуализациите на SDK на всеки 2–3 седмици, особено преди публикуване на нова версия на приложението в Google Play.

Настройка на системен образ за емулатора

За стартиране на емулатора с конкретно API Level трябва да инсталирате System Image от същата версия. SDK Manager позволява изтегляне на образи с различни архитектури (x86_64, arm64-v8a) и типове (Google APIs, Google Play, AOSP). След изтегляне на образа AVD Manager създава виртуално устройство на негова основа.

# Инсталирай System Image с Google APIs за API 35
sdkmanager "system-images;android-35;google_apis;x86_64"

# Създай AVD чрез команден ред
avdmanager create avd -n pixel8 -k "system-images;android-35;google_apis;x86_64"

# Списък на създадените AVD
avdmanager list avd

compileSdk, targetSdk и minSdk в Gradle

Три параметъра в build.gradle определят работата на приложението с SDK Platform. compileSdk — API Level, използвано за компилиране. Този параметър посочва кои класове на Android API са достъпни в кода. compileSdk трябва да бъде най-новото от трите и не влияе на поведението по време на изпълнение — приложението се компилира, но използва само API-тата, които са на устройството.

minSdk — минималното API Level, на което приложението може да бъде инсталирано. Google Play няма да позволи инсталиране на приложението на устройство с версия по-ниска от minSdk. Този параметър определя прага на съвместимост и влияе на обхвата на аудиторията. Колкото по-ниско е minSdk, толкова повече устройства се поддържат, но толкова по-малко нови API могат да се използват без проверки.

targetSdk — API Level, на което приложението е тествано. Системата Android използва targetSdk за прилагане на поведенчески промени: ако приложението не е актуализирано до новото API Level, системата включва режим на съвместимост за по-стари версии. Google Play изисква targetSdk да не бъде по-ниско от определено ниво — за 2026 г. това е API 34 (Android 14).

Примерна конфигурация на Gradle

android {
    compileSdk 35

    defaultConfig {
        applicationId "com.example.app"
        minSdk 26
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

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

// Версията на Android SDK трябва да бъде инсталирана чрез SDK Manager
// sdkmanager "platforms;android-35"

Как да изберете compileSdk, minSdk и targetSdk

Стратегията за избор зависи от целите на проекта. За ново приложение: compileSdk — последният стабилен (35 в началото на 2026), minSdk — API 26 (Android 8.0, покрива 95% от устройствата), targetSdk — последният стабилен. За актуализиране на съществуващо приложение: повишете compileSdk веднага, targetSdk — след тестване на всички поведенчески промени, minSdk — само ако е необходимо да се откажете от остарели устройства.

Google изисква targetSdk да бъде актуализиран в рамките на една година след излизането на нова версия на Android. Приложенията, които не отговарят на това изискване, не могат да публикуват актуализации в Google Play. За проследяване на крайните срокове използвайте официалния календар за актуализации на Android OS.

Примери за работа с SDK Platform в код

При разработка за различни версии на Android трябва да се вземе предвид наличието на API. Ако приложението използва compileSdk 35, но работи на устройство с API 31, извикването на методи, добавени в API 34, ще доведе до NoSuchMethodError или AbstractMethodError. За безопасно извикване на нови API се използват проверки на версията чрез Build.VERSION.SDK_INT.

Проверка на API Level по време на изпълнение

class FeatureChecker {
    fun registerNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            // Notification channels са достъпни от API 26
            val channel = NotificationChannel(
                "updates",
                "Актуализации",
                NotificationManager.IMPORTANCE_DEFAULT
            )
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

Използване на нови API с @RequiresApi

За методи, които се извикват само на определени версии, използвайте анотация @RequiresApi. Това подсказва на lint проверките, че методът е безопасен, и изключва предупрежденията. В комбинация с проверката на SDK_INT, анотацията прави кода по-чист и по-разбираем за рецензентите.

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun scheduleExactAlarm(manager: AlarmManager, time: Long) {
    // API 34: scheduleExact с флаг SCHEDULE_EXACT_ALARM
    if (manager.canScheduleExactAlarms()) {
        manager.setExact(AlarmManager.RTC_WAKEUP, time, pendingIntent)
    } else {
        // Искаме разрешение SCHEDULE_EXACT_ALARM
        val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
        context.startActivity(intent)
    }
}

fun safeScheduleAlarm(context: Context, triggerTime: Long) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleExactAlarm(getAlarmManager(context), triggerTime)
    } else {
        // Старият метод setExact без проверка на разрешения
        getAlarmManager(context).setExact(AlarmManager.RTC_WAKEUP, triggerTime, pendingIntent)
    }
}

Определяне на инсталирания SDK Platform

Понякога трябва да разберете коя версия на SDK Platform е инсталирана на устройството на разработчика или в CI. Това може да се направи чрез ADB или програмно в кода на приложението. Познаването на API Level на устройството помага при тестване на поведение, специфично за версията.

fun logDeviceInfo() {
    with (Build.VERSION) {
        Log.d("SDK_Demo", "SDK_INT: $SDK_INT")
        Log.d("SDK_Demo", "RELEASE: $RELEASE")
        Log.d("SDK_Demo", "CODENAME: $CODENAME")
        Log.d("SDK_Demo", "PREVIEW_SDK_INT: $PREVIEW_SDK_INT")
    }
    // Изход: SDK_INT: 35, RELEASE: 15, CODENAME: REL
}