API Level: bu nədir, API versiyaları və targetSdk

API Level Android nədir?

API Level Android — Android Framework API-nin hər ictimai buraxılışına təyin edilən tam ədədli identifikator. İlk buraxılış Android 1.0 API Level 1-ə malik idi, 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. Hər yeni API Level yeni siniflər, metodlar, sabitlər, icazələr əlavə edə və mövcud olanların davranışını dəyişə bilər.

API Level hər buraxılışla ciddi şəkildə 1 artmır. Məsələn, Android 4.4W (Wear) API 20-yə malikdir, Android 5.0 isə API 21-ə. Boşluqlar daxili iterasiyalar və Wear OS cihazları ilə bağlıdır. Tərtibatçı üçün versiya adını (KitKat, Lollipop, Tiramisu) yox, onun API Level-ni bilmək vacibdir — kodda uyğunluq yoxlamaları üçün məhz bu istifadə olunur.

API Level-in əsas məqsədi geriyə uyğunluqdur. API 34-ə qarşı tərtib edilmiş tətbiq API 34 və aşağısı olan cihazlarda işləyə bilər (əgər yoxlamadan yeni API-lər istifadə etmirsə). Android Runtime (ART) sistem səviyyəsində API çağırışlarını yoxlayır və tətbiqin targetSdkVersion-dan asılı olaraq davranış dəyişikliklərini tətbiq edir.

Android API Level-i necə idarə edir

Tətbiq quraşdırılarkən, PackageManager cihazın API Level-inin AndroidManifest.xml-dəki minSdkVersion >= olub-olmadığını yoxlayır. Şərt yerinə yetirilməzsə — quraşdırma "App not installed" mesajı ilə bloklanır. İş vaxtı ərzində Android Runtime daha yüksək API Level tələb edən API çağırışlarını izləyir və metod cari versiyada mövcud deyilsə NoSuchMethodError və ya UnsatisfiedLinkError yaradır.

minSdk, targetSdk, compileSdk: fərqlər və hər parametrin rolu

build.gradle faylında (Module: app) tərtibatçı üç API Level parametri təyin edir: minSdkVersion, targetSdkVersion və compileSdkVersion. Bunları qarışdırmaq başlanğıc Android tərtibatçılarının ən çox yayılmış səhvlərindən biridir. Hər parametr uyğunluğun fərqli aspektindən məsuldur və onların dəyərləri uyğun olmalıdır.

minSdkVersion

minSdkVersion tətbiqin quraşdırılıb işlədilə biləcəyi minimum API Level-dir. minSdk-dən aşağı API Level-ə malik cihazlar Google Play-də tətbiqi görmür və onu quraşdıra bilmir. Dəyər hədəf auditoriyaya əsasən seçilir: minSdk 21 (Android 5.0) cihazların 97%-ni əhatə edir, minSdk 26 (Android 8.0) — təxminən 85%, minSdk 31 (Android 12) — təxminən 55% (Android Studio Distribution Dashboard, 2026 məlumatları). minSdk nə qədər aşağı olsa, əhatə dairəsi bir o qədər geniş olar, lakin geriyə uyğunluq kodu bir o qədər çox olar.

targetSdkVersion

targetSdkVersion tətbiqin sınaqdan keçirildiyi API Level-dir. Android davranış dəyişikliklərini tətbiq etmək üçün targetSdk-dən istifadə edir: tətbiq targetSdk 33 göstərirsə, sistem API 33-də təqdim edilən bütün davranış dəyişikliklərini aktivləşdirir. targetSdk 31-dirsə, sistem API 32-33 dəyişikliklərini tətbiq etmir, köhnə davranışla uyğunluğu qoruyur. Bu, təhlükəsizlik üçün ən vacib parametrdir: Google Play targetSdk-nin cari API Level-dən 1 ildən köhnə olmamasını tələb edir.

compileSdkVersion

compileSdkVersion kodun tərtib edildiyi Android SDK versiyasıdır. Tərtib zamanı hansı API-lərin mövcud olduğunu müəyyən edir. compileSdk targetSdk-dən >= olmalı və ideal olaraq ən son sabit API Level-ə bərabər olmalıdır. compileSdk-ni artırmaq iş vaxtı davranışına təsir etmir — yalnız tərtibçi üçün yeni API-lərin mövcudluğuna təsir edir. compileSdk artırıldıqdan sonra kodu istifadədən çıxarılmış API-lər və yeni icazə tələbləri üçün yoxlamaq lazımdır.

// build.gradle.kts — API Level konfiqurasiya nümunəsi
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 nümunəsində compileSdk = 36 (yazı zamanı ən son), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36 bütün Android 16 API-lərinə giriş verir. targetSdk 36 bütün Android 16 davranış dəyişikliklərini aktivləşdirir. minSdk 26 ~85% cihazları əhatə edir. AndroidX Activity KTX və AppCompat fraqmentlər və mövzular üçün geriyə uyğunluq təmin edir.

AndroidManifest.xml

minSdk və targetSdk parametrləri AndroidManifest.xml-də də göstərilə bilər, lakin müasir layihələr build.gradle istifadə edir — Gradle dəyərləri manifesti ləğv edir. Manifestdə Gradle build config istifadə etməyən kitabxanalar və modullar üçün göstərmək faydalı ola bilər.

Davranış dəyişiklikləri: targetSdk tətbiq davranışına necə təsir edir

Davranış dəyişiklikləri yalnız targetSdk >= müəyyən API Level olan tətbiqlərə tətbiq edilən Android sisteminin işləmə tərzində dəyişikliklərdir. Hər yeni Android buraxılışı yenilənmədikdə mövcud tətbiqləri poza biləcək davranış dəyişiklikləri təqdim edir. Bu, Android-in əsas təhlükəsizlik mexanizmidir: köhnə tətbiqlər əvvəlki kimi işləməyə davam edir, yeniləri cari qaydalara əməl edir.

Versiyalara görə əsas davranış dəyişiklikləri

Android 10 (API 29) — Scoped Storage: targetSdk 29+ olan tətbiqlərin ortaq fayl sisteminə birbaşa girişi yoxdur, yalnız MediaStore, SAF və ya öz yaddaşı vasitəsilə. Android 11 (API 30) — Package Visibility: paket filtri, tətbiqlər yalnız qarşılıqlı əlaqədə olduqları quraşdırılmış paketləri görür. Android 12 (API 31) — Foreground Service Notification: bütün ön plan xidmətləri başlamadan sonra 10 saniyə ərzində bildiriş göstərməlidir. Android 13 (API 33) — POST_NOTIFICATIONS: push bildirişləri üçün iş vaxtı icazəsi. Android 14 (API 34) — Foreground Service Types: manifestdə ön plan xidmət növünün məcburi bəyanı.

// Android 13 (API 33) davranış dəyişikliklərinin idarə edilməsi: 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 icazəsi yalnız API 33+ ilə işləyir
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // API 33-dən aşağı icazə tələb olunmur
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // İcazə artıq verilib, bildirişlər göndərilə bilər
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // İcazənin nə üçün lazım olduğunu izah edin
                activity.showRationale()
            }

            else -> {
                // İcazə tələb edin
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Bildiriş yaradın və göstərin
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Bildiriş")
            .setContentText("Yeni mesaj")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Activity-də requestPermissionLauncher qeydiyyatdan keçirin
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // İcazə alındı
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }
}

Kotlin-də POST_NOTIFICATIONS idarə edilməsi nümunəsi: Build.VERSION.SDK_INT >= TIRAMISU yoxlanması, ActivityResultContracts.RequestPermission vasitəsilə iş vaxtı icazəsinin tələbi, nəticənin callback-də idarə edilməsi. Bu icazə olmadan targetSdk 33+ olan tətbiq push bildirişləri göstərə bilməz. API 33-dən aşağı icazə tələb olunmur — yoxlama kodu mövcud olmayan API-lərin çağırılmasının qarşısını alır.

Scoped Storage (Android 10+)

Scoped Storage ən əhəmiyyətli davranış dəyişikliklərindən biridir. API 29-dan (targetSdk 29+) başlayaraq, tətbiq Pictures, Downloads, Music və Documents qovluqlarına birbaşa fayl girişi əldə edə bilməz. Bunun əvəzinə media üçün MediaStore, ixtiyari fayllar üçün SAF (Storage Access Framework) və öz yaddaşı üçün getExternalFilesDir() istifadə olunur. İstisna MANAGE_EXTERNAL_STORAGE icazəsi olan tətbiqlərdir ki, bu da Google Play təsdiqini tələb edir.

Google Play-in API Level və targetSdk üçün tələbləri

Google Play tətbiqləri nəşr etmək üçün targetSdkVersion üçün məcburi tələblər müəyyən edir. Avqust 2024-dən etibarən Google Play targetSdkVersion >= API 33 (Android 13) tələb edir. Hər il hədd yüksəlir: yeni tətbiqlər və yeniləmələr cari əsas API Level-dən 1 ildən köhnə olmayan targetSdk göstərməlidir. Tələbin pozulması nəşrin bloklanmasına və tətbiqin mağazadan silinməsinə səbəb olur.

Nə üçün Google Play tələbləri sərtləşdirir

Əsas səbəb təhlükəsizlikdir. Hər yeni Android API Level hücum vektorlarını bağlayan davranış dəyişiklikləri təqdim edir: Scoped Storage (API 29) fayl oğurluğunun qarşısını alır, POST_NOTIFICATIONS (API 33) spam bildirişlərdən qoruyur, Foreground Service Types (API 34) gizli fon xidmətlərini məhdudlaşdırır. Aşağı targetSdk olan tətbiqlər bu qorunmaları almır və istifadəçilər üçün təhlükə yaradır. Google Play müasir cihazlarda köhnəlmiş tətbiqlərə icazə verə bilməz.

Tələblərə uyğunluğun yoxlanması

Google Play Console APK/AAB yükləyərkən targetSdkVersion yoxlayır. targetSdk tələb olunandan aşağıdırsa — konsol "Your app currently targets API level X and must target at least API level Y" mesajı ilə nəşri bloklayır. Tərtibatçı build.gradle-ı yeniləməli, tətbiqi yenidən tərtib etməli, davranış dəyişikliklərini sınamalı və yenidən yükləməlidir. AAB formatı bütün yeni nəşrlər üçün tövsiyə olunur (Avqust 2021-dən məcburidir).

Kodda API Level yoxlanması: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT tətbiqin işlədiyi cihazın API Level-ni ehtiva edən statik tam ədəd sabitidir. İş vaxtı Android versiyası yoxlamaları üçün əsas vasitədir. Build.VERSION_CODES hər API Level üçün adlandırılmış sabitlər ehtiva edir: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). if (SDK_INT >= VERSION_CODES.TIRAMISU) vasitəsilə müqayisə standart nümunədir.

// Android kodunda API Level yoxlanması nümunələri
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Əsas API Level yoxlanması
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Yoxlama ilə adaptiv API çağırışı
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable yalnız API 26 (Android 8) ilə mövcuddur
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // köhnə cihazlar üçün fallback
    }

    // 3. POST_NOTIFICATIONS icazə yoxlanması (yalnız API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. API Level-ə görə şəkil təminatçısı seçimi
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ PhotoPicker istifadə edir
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ Intent ACTION_OPEN_DOCUMENT istifadə edir
                "open_document"
            }
            else -> {
                // Legacy: ACTION_GET_CONTENT (bütün versiyalar)
                "get_content"
            }
        }
    }

    // 5. @TargetApi vasitəsilə Java üslublu yoxlama (geriyə uyğunluq üçün)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Scoped Storage davranışı SDK_INT-dan deyil, targetSdk-dan asılıdır
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Analitika üçün quruluş məlumatı
    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
        )
    }
}

// Sınaq
fun main() {
    val helper = ApiLevelHelper()
    println("API Level: ${VERSION.SDK_INT}")
    println("Is Tiramisu+: ${helper.isAtLeastTiramisu()}")
}

ApiLevelHelper sinfi bütün əsas API Level yoxlama nümunələrini göstərir: SDK_INT >= VERSION_CODES ilə isAtLeastTiramisu, köhnə versiyalar üçün fallback ilə getAdaptiveIcon, when çoxşaxəli ilə getImagePickerProvider, analitika üçün getDeviceApiInfo. Əsas qayda — SDK_INT yoxlanmadan yeni API-ləri çağırmamaq, əks halda tətbiq köhnə cihazlarda NoSuchMethodError ilə çökəcək.

ANT (Android New API) və lint

Android Studio-ya minSdkVersion-dan yuxarı API istifadəsi barədə xəbərdarlıq edən statik analizator lint daxildir. SDK_INT yoxlanmadan metod çağırılırsa, lint onu səhv kimi vurğulayır: "Call requires API level 34 (current min is 26)". Həll yolları: metoda @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) əlavə etmək və ya SDK_INT-nin if yoxlanması. @TargetApi istifadədən çıxarılmış annotasiyadır, @RequiresApi tövsiyə olunur.

API Level və Android versiyalarının uyğunluq cədvəli

API Level cədvəli tərtibatçı üçün istinad vasitəsidir. Cihazın API Level-ni bilməklə Android versiyasını və mövcud funksiyaları müəyyən etmək olar. Cədvəl API Level 1-dən (2008) API Level 36-ya (2025) qədər bütün əsas Android buraxılışlarını sadalayır. Kod adları (Cupcake, Donut, Tiramisu, VanillaIceCream) Google daxilində və VERSION_CODES-da istifadə olunur.

Cədvəl: davranış dəyişiklikləri üçün hədd API Level-ləri

Aşağıdakı cədvəl targetSdk artırılarkən geriyə uyğunluğu pozan davranış dəyişiklikləri təqdim edən əsas API Level-ləri göstərir: