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-а потребно је проверити код за коришћење застарелих 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 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: све услуге у предњем плану морају приказати обавештење у року од 10 секунди након покретања. Android 13 (API 33) — POST_NOTIFICATIONS: дозвола током извршавања за пусх обавештења. Android 14 (API 34) — Foreground Service Types: обавезна декларација типа услуге у предњем плану у манифесту.

// Обрада 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+ не може приказивати пусх обавештења. Испод API 33 дозвола није потребна — код провере спречава позив недоступних API-ја.

Scoped Storage (Android 10+)

Scoped Storage — једна од најзначајнијих behavioural changes. Почевши од 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 пооштрава захтеве

Главни разлог — безбедност. Сваки нови 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-а: