compileSdkVersion: основи, нові API та налаштування в Gradle

Що таке compileSdkVersion в Android?

compileSdkVersion — цілочисельний параметр у build.gradle, який вказує, проти якої версії Android SDK компілювати код. Коли ви пишете код, що використовує класи з android.* або androidx.*, компілятор звіряє їх з API, доступними у вказаній версії compileSdk. Якщо метод з'явився в API 36, а compileSdk = 35, код не скомпілюється. Якщо compileSdk = 36 — код скомпілюється, але на пристрої з API 35 при виклику цього методу без перевірки станеться помилка.

compileSdkVersion завантажується з Android SDK Platform, встановленої через SDK Manager в Android Studio. Кожен API Level має свою платформу: android-21, android-29, android-34, android-35, android-36. Платформа містить android.jar — набір класів, методів і констант, з якими працює компілятор Kotlin/Java. Якщо платформа не встановлена, Gradle завантажить її автоматично через sdkmanager при першій збірці.

AGP (Android Gradle Plugin) версії 8.7+ рекомендує вказувати compileSdk як ціле число через compileSdk = 36 у Kotlin DSL, без префікса android-. compileSdk також можна вказати через compileSdkVersion 36 у Groovy DSL або compileSdkPreview для попередніх версій SDK (developer previews). compileSdkPreview використовується для тестування майбутніх API Level до офіційного релізу.

// build.gradle.kts — налаштування compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — останній стабільний API Level (Android 16)
    compileSdk = 36

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

// Альтернативно: compileSdkPreview для попередніх версій
// compileSdkPreview = "Baklava"

У прикладі compileSdk = 36 надає доступ до всіх API Android 16 (Baklava). Android SDK Platform 36 має бути встановлена в SDK Manager. compileSdkPreview з ім'ям "Baklava" можна використовувати для тестування нестабільних API до офіційного релізу платформи. Після релізу попередній перегляд замінюється на стабільний compileSdk = 36.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Три параметри API Level у build.gradle — compileSdkVersion, targetSdkVersion та minSdkVersion — часто плутають. Кожен відповідає за різний аспект сумісності, і їхні значення мають бути узгоджені за правилом compileSdk >= targetSdk >= minSdk. minSdk — нижня межа: пристрої нижче не побачать застосунок. targetSdk — точка тестування: поведінкові зміни вмикаються до цього рівня. compileSdk — стеля: API вище цього рівня недоступні для компілятора.

Ключове практичне правило: compileSdk можна підвищити без будь-якого тестування на пристроях. Це безпечна операція, яка лише надає компілятору нову версію android.jar. Єдиний ризик — застарілі API, які можуть бути видалені в новій версії платформи, але це виявляється на етапі компіляції та легко виправляється. Підвищення targetSdk, навпаки, потребує повного циклу QA.

Чому compileSdk може бути вищим за targetSdk? Уявіть, що вийшла Android 16 (API 36) з новими API, які ви хочете використовувати в коді, але поведінкові зміни API 36 ви ще не тестували. Ви встановлюєте compileSdk = 36 (нові API доступні), targetSdk = 35 (поведінкові зміни API 36 вимкнені). Код скомпілюється, використовуватиме нові методи під SDK_INT-перевірками, а поведінкові зміни API 36 не зламають застосунок, тому що targetSdk = 35.

Приклади коректних комбінацій

compileSdk = 36, targetSdk = 36, minSdk = 26 — повна сумісність з останніми API та поведінковими змінами, охоплення 85% пристроїв. compileSdk = 36, targetSdk = 34, minSdk = 26 — нові API доступні, поведінкові зміни тільки до API 34. compileSdk = 35, targetSdk = 36 — некоректно: compileSdk нижче targetSdk, API 36 недоступні, хоча поведінкові зміни 36 активні.

Як оновити compileSdkVersion: покрокова інструкція

Оновлення compileSdkVersion — одна з найпростіших і найбезпечніших операцій в Android-проекті. На відміну від targetSdk, воно не потребує тривалого тестування поведінкових змін. Однак є кілька кроків, які потрібно виконати, щоб уникнути помилок компіляції та попереджень про застарілість.

Крок 1 — встановіть нову платформу через SDK Manager в Android Studio: Tools → SDK Manager → SDK Platforms → виберіть новий API Level. Якщо не встановити платформу, Gradle спробує завантажити її автоматично, але це може сповільнити першу збірку. Крок 2 — змініть compileSdk у build.gradle на нове значення. Крок 3 — виконайте збірку (Build → Make Project) та виправте помилки компіляції.

Крок 4 — перевірте застарілі API. Після підвищення compileSdk деякі методи можуть бути позначені @Deprecated з позначкою "removed in API X". Android Studio підсвічує закресленням і видає попередження. Замініть застарілі виклики на нові альтернативи. Якщо альтернатива потребує API Level вище minSdk, додайте перевірку під час виконання. Крок 5 — перевірте залежності: деякі бібліотеки можуть потребувати певної версії compileSdk. AGP 8.7+ рекомендує compileSdk = 36.

// Після підвищення compileSdk: заміна застарілих API
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ДО: застарілий метод (може бути видалений у новому API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Може бути застарілим в API 36
    }

    // ПІСЛЯ: нова альтернатива (якщо доступна)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Новий API з compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Приклад нового API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Клас CompileSdkMigration показує коректний патерн міграції. Старий метод memoryClass може бути видалений у новому API — компілятор видасть помилку. Нова альтернатива getMemoryClassSafe доступна тільки на API 36+, тому вона викликається під перевіркою SDK_INT >= BAKLAVA. Для старих пристроїв використовується запасний варіант з @Suppress("DEPRECATION").

Робота з новими API: умовні перевірки та запасний варіант

Нові API, доступні завдяки підвищенню compileSdkVersion, не можна викликати безпосередньо, якщо minSdkVersion нижче цього API Level. Без перевірки під час виконання застосунок впаде з AbstractMethodError, NoSuchMethodError або VerifyError на старих пристроях. Основний захисний механізм — перевірка Build.VERSION.SDK_INT з викликом нового API тільки при достатньому API Level та запасний варіант для старих версій.

AndroidX надає зворотні порти багатьох нових API, що дозволяє використовувати сучасні методи навіть при низькому compileSdk. Наприклад, Activity Result API з androidx.activity:activity-ktx:1.9.3 працює на всіх версіях Android, починаючи з API 14. NotificationCompat з AndroidX дозволяє використовувати сучасні сповіщення на старих API. PhotoPicker доступний через ActivityResultContracts.PickVisualMedia починаючи з API 34+.

// Безпечний виклик нового API з compileSdk 36 та minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: новий метод роботи з кольором
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Новий API з compileSdk 36 — потребує API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Запасний варіант: ручне форматування для старих API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: зворотний порт не потрібен — перевірка SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Використання в Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

Клас NewApiHelper демонструє безпечний виклик нового API Color.toArgbHexString (гіпотетичний API 36) із запасним форматуванням для старих версій. Ключовий принцип: compileSdk дає доступ до виклику нових методів у коді, але перевірка SDK_INT під час виконання захищає від крашу на старих пристроях. Без перевірки SDK_INT застосунок з minSdk 26 та compileSdk 36 буде падати на Android 8-15.

AGP (Android Gradle Plugin) та compileSdkVersion

Android Gradle Plugin (AGP) — основний інструмент збірки Android-застосунків. Кожна версія AGP підтримує певний діапазон compileSdkVersion. AGP 8.7.x (випущений у 2026 році) потребує compileSdk >= 34 та рекомендує compileSdk = 36. AGP 8.5.x підтримує compileSdk 33-35. Якщо compileSdk нижче мінімального для AGP, збірка завершиться помилкою: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) також прив'язаний до compileSdkVersion. Якщо проект використовує нативний код на C/C++ через NDK, compileSdk визначає версію заголовних файлів та бібліотек. NDK r27+ рекомендує compileSdk 36. Для бібліотек з .so-файлами compileSdk впливає на мінімальний API Level для нативного коду через APP_MIN_SDK_VERSION в Application.mk.

Gradle (7.6+) та Kotlin (2.0+) також впливають на сумісність з compileSdk. AGP 8.7+ потребує Gradle 8.9+ та Kotlin 2.0+. При підвищенні compileSdk рекомендується оновити AGP, Gradle та Kotlin до останніх стабільних версій. Перевірте сумісність в офіційній таблиці сумісності Android Gradle Plugin.

Типові проблеми при підвищенні compileSdk

Проблеми при підвищенні compileSdkVersion поділяються на три категорії: помилки компіляції, попередження про застарілість та несумісність під час виконання. Помилки компіляції — методи видалено з API і код не компілюється. Попередження про застарілість — методи позначено @Deprecated, код компілюється з попередженнями. Несумісність під час виконання — нові API обов'язкові для певної функціональності та викликають помилку при недостатньому API Level на пристрої.

Перша типова проблема — "Cannot resolve symbol X". Це означає, що клас або метод було видалено з публічного API в новій версії SDK. Рішення: знайти альтернативу в новій платформі або використати AndroidX-еквівалент. Наприклад, клас AsyncTaskLoader був застарілим в API 28 та видалений з публічного API в новіших версіях. Альтернатива — Kotlin Coroutines або WorkManager.

Друга проблема — зміна сигнатури методу. У новій версії API метод міг змінити кількість або типи параметрів. Компілятор Kotlin/Java видає помилку "None of the following functions can be called with the arguments supplied". Рішення: оновити виклик методу під нову сигнатуру або додати перевірку SDK_INT з викликом старої сигнатури для старих пристроїв.

// Вирішення проблем при підвищенні compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Проблема: метод hasSystemFeature змінив сигнатуру в API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Нова сигнатура: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Стара сигнатура: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Проблема: клас видалено, використовуємо AndroidX еквівалент
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Замість android.app.FragmentManager (видалено) використовуємо
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Клас CompileSdkProblemFixer вирішує типові проблеми: змінену сигнатуру hasSystemFeature (гіпотетична зміна в API 36) оброблено через SDK_INT-перевірку з викликом правильної версії методу. Видалений клас android.app.FragmentManager замінено на AndroidX-еквівалент. Для старих викликів, де немає альтернативи, використовується @Suppress("DEPRECATION") з коментарем про причину збереження.