minSdkVersion: bu nədir, Android-in minimum versiyasını necə seçməli

Android-də minSdkVersion nədir?

minSdkVersion — proqramın quraşdırılması üçün minimum Android API Level-i təyin edən build.gradle faylındakı tam ədəd parametri. Cihazın API Level-i göstərilən dəyərdən aşağı olarsa, PackageManager quraşdırmanı bloklayır və Google Play Store proqramı belə bir cihaz üçün axtarış nəticələrindən gizlədir. minSdkVersion build mərhələsində AndroidManifest.xml faylına <uses-sdk android:minSdkVersion> teqi vasitəsilə yazılır və hər quraşdırmada yoxlanılır.

minSdkVersion dəyəri — auditoriya əhatəsi ilə yeni API-lərə giriş arasında kompromisdir. minSdk nə qədər aşağı olsa, bir o qədər çox cihaz proqramı quraşdıra bilər, xüsusilə köhnə Android smartfonlarının populyar olduğu inkişaf etməkdə olan regionlarda. minSdk nə qədər yüksək olsa, bir o qədər az geriyə uyğunluq kodu tələb olunur və daha çox müasir API icra vaxtı yoxlamaları olmadan əlçatan olur. Android Jetpack və AndroidX kitabxanaları bir çox yeni API-lərin köhnə Android versiyalarına backportlarını təmin edir ki, bu da funksionallığı itirmədən daha aşağı minSdk seçməyə imkan verir.

minSdkVersion proqramlaşdırmanın bütün mərhələlərinə təsir edir: statik analiz (lint minSdk-dən xəbərdarlıqlar üçün istifadə edir), asılılıqların uyğunluğu (kitabxanalar öz minSdk-lərini tələb edə bilər), test etmə (minSdk olan cihazlarda test etmək lazımdır) və Google Play Console (auditoriya əhatəsi minSdk əsasında hesablanır). minSdkVersion dəyişdirmək — layihə konfiqurasiyasında ən məsuliyyətli qərarlardan biridir, çünki koda, testlərə və istifadəçi bazasına təsir edir.

minSdkVersion harada göstərilir

Build.gradle.kts (Kotlin DSL) — Android layihələrində müasir standart. minSdk parametri modul səviyyəsində defaultConfig blokunda təyin edilir. Dəyər müxtəlif build types və product flavors üçün dəyişdirilə bilər ki, bu da əsas dəyəri dəyişmədən aşağı API-lərdə test etməyə imkan verir.

// build.gradle.kts — minSdk-nin əsas konfiqurasiyası
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // Müxtəlif flavor-lar üçün minSdk-nin dəyişdirilməsi
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

Nümunədə minSdk = 26 Android 8.0 Oreo-ya uyğundur. Bu 2026-cı ildə məşhur dəyərdir: Android Studio Distribution Dashboard-a görə cihazların yalnız ~15%-ni kəsir. compileSdk = 36 bütün Android 16 API-lərinə giriş verir, targetSdk = 36 isə ən son versiyanın davranış dəyişikliklərini aktivləşdirir. Debug build-lər üçün minSdk köhnə emulyatorlarda test etmək üçün aşağı salına bilər.

minSdkVersion necə seçilir: amillər və strategiya

minSdkVersion seçimi — hədəf auditoriyanın, API tələblərinin və kitabxana ekosisteminin təhlilinə əsaslanan strateji qərar. Bütün layihələr üçün yeganə düzgün dəyər yoxdur. 2026-cı ildə Android Studio yeni layihələr üçün minSdk = 26 (Android 8.0) əsas səviyyə kimi tövsiyə edir, lakin B2B tətbiqləri və ya korporativ həllər üçün daha aşağı və ya yüksək dəyərlər məqbuldur.

minSdkVersion seçim amilləri

Birinci amil — Distribution Dashboard. Android Studio Google Play məlumatları əsasında API Level üzrə aktiv cihazların aylıq yenilənən statistikasını təqdim edir. minSdkVersion hədəf bazarın aktiv cihazlarının ən azı 90-95%-ni əhatə etməlidir. Afrika və Cənub-Şərqi Asiyada auditoriyası olan beynəlxalq tətbiqlər üçün köhnə cihazların yüksək payı səbəbindən minSdk 21-ə (Android 5.0) endirilməlidir.

İkinci amil — asiılılıq tələbləri. Hər kitabxananın öz manifestində göstərilən öz minSdkVersion-u var. Kitabxana minSdk 29 tələb edirsə və tətbiq — minSdk 26, build manifest merger xətası ilə bitəcək. Müasir Google Play Services kitabxanaları minSdk 21, Firebase — minSdk 21, əksər Jetpack kitabxanaları — minSdk 21 və ya 26, Compose BOM — minSdk 21-ə malikdir. Compose üçün minimum hədd — API 21.

Üçüncü amil — zəruri API-lər. Tətbiqin əsas funksionallığı yalnız müəyyən səviyyədən əlçatan olan API tələb edirsə (məsələn, PhotoPicker — API 34, Predicted Navigation — API 35), bu minSdk-ni artırmağa əsas ola bilər. Lakin daha tez-tez AndroidX backportları (Activity Result API, NotificationCompat) və icra vaxtı yoxlamaları kombinasiyasından istifadə edilir ki, aşağı minSdk qorunsun.

Addım-addım seçim strategiyası

Addım 1: Android Studio-nu açın, File → New Project və sehrbazda tövsiyə olunan minSdk-ə baxın. Addım 2: Android Studio-da Distribution Dashboard-ı yoxlayın (View → Tool Windows → App Inspection → Distribution Dashboard). Addım 3: layihənin asılılıqlarını təhlil edin — build edin və manifest merger konfliktlərini həll edin. Addım 4: X səviyyəli API-lərdən hansının həqiqətən backportsuz istifadə edildiyini qiymətləndirin. Addım 5: hədəf auditoriyanın 90%+-nı əhatə edən və bütün asılılıqlarla uyğun olan minimum dəyəri minSdk olaraq təyin edin.

Cihaz əhatəsi: API Level paylanması (2026)

Cihaz paylanması API Level üzrə — hər rüb dəyişən dinamik göstəricidir. 2026-cı il iyun ayı üçün Android Studio Distribution Dashboard məlumatına görə, aktiv Android cihazlarının təxminən 85%-i API 26 (Android 8.0) və daha yuxarı, 72%-i API 29 (Android 10) və daha yuxarı, 55%-i API 31 (Android 12) və daha yuxarı işləyir. Çin bazarı bir çox Huawei cihazlarında Google Play Services olmaması səbəbindən öz statistikasına malikdir.

GMS cihazları (Google Mobile Services) daha sürətli yenilənir: onlarda API 31+ payı istehsalçılara Google Play-in məcburi tələbləri sayəsində 68%-ə çatır. Qeyri-GMS cihazları (Huawei, Honor, bəzi Çin markaları) daha köhnə paylanmaya malikdir: onlarda API 31+ payı təxminən 35% təşkil edir. Tətbiq beynəlxalq bazara yönəlmişsə, qlobal statistikaya əsaslanın. Çin bazarına yönəlmişsə, qeyri-GMS seqmentini nəzərə alın.

Nəticə: beynəlxalq tətbiq üçün minSdk 26 minimal geriyə uyğunluq xərcləri ilə cihazların 85%-ni əhatə edir. İnkişaf etməkdə olan regionlarda auditoriyası olan tətbiqlər üçün minSdk 21 (97% əhatə) əsaslandırılmışdır, lakin köhnəlmiş API-lərlə iş üçün daha çox kod tələb edəcək. İdarə olunan cihaz parkı olan Enterprise tətbiqləri üçün minSdk 31 təyin edib fallback kodundan tamamilə qurtula bilərsiniz.

Geriyə uyğunluq: AndroidX, lint və @RequiresApi

Geriyə uyğunluq — aşağı minSdkVersion-da əsas çətinlik. AndroidX (əvvəllər Support Library) müasir API-lərin köhnə Android versiyalarına backportlarını təmin edir: Material Design üçün AppCompatActivity, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat və onlarla digər komponentlər. Yerli API-lər əvəzinə AndroidX ekvivalentlərindən istifadə — uyğunluğa ilk addımdır.

lint (Android Studio-nun statik analizatoru) minSdkVersion-dan yuxarı API çağırışları üçün kodu skan edir. Metod @RequiresApi ilə minSdk-dən yuxarı API Level-də qeyd olunub və yoxlamasız çağırılıbsa, lint xətanı vurğulayır. Xəbərdarlığı aradan qaldırmaq üçün metoda @SuppressLint("NewApi") annotasiyasından və ya bütün funksiyaya @RequiresApi(Build.VERSION_CODES.TIRAMISU) annotasiyasından istifadə edin. İcra vaxtı yoxlamaları Build.VERSION.SDK_INT vasitəsilə — köhnə cihazlarda yeni API-ləri təhlükəsiz çağırmaq üçün əsas mexanizmdir.

// Geriyə uyğunluq nümunəsi: PhotoPicker (API 34+) və fallback
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API (AndroidX) — istənilən API Level-də işləyir
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker yalnız API 34-dən etibarən mövcuddur
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // PhotoPicker-dən istifadə edirik (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Fallback: GetContent (bütün versiyalarda işləyir)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Bu metodu API-də çağırmaq olmaz < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

ImagePickerActivity sinfi üç səviyyəli geriyə uyğunluğu nümayiş etdirir. AndroidX-dən Activity Result API bütün API Level-lərdə işləyir, buna görə əsas şəkil seçimi üçün minSdk əhəmiyyət kəsb etmir. PhotoPicker (ACTION_PICK_IMAGES) yalnız API 34-dən etibarən mövcuddur və GetContent-ə fallback ilə SDK_INT yoxlaması altında çağırılır. usePhotoPickerOnly metodu @RequiresApi ilə qeyd olunub — lint onu yoxlamasız çağırmağa icazə verməz. AndroidX-dən AppCompat avtomatik olaraq mövzunu, fraqmentləri və animasiyaları əməliyyat sistemi versiyasına uyğunlaşdırır.

Kitabxana və modullarda minSdkVersion

Kitabxanalar (AAR, JAR) da öz manifestlərində göstərilən minSdkVersion-a malikdir. Kitabxana qoşularkən Gradle uyğunluğu yoxlayır: kitabxananın minSdk-i tətbiqin minSdk-indən yüksəkdirsə, build xəta ilə başa çatır. İctimai kitabxanalar üçün istehlakçıları məhdudlaşdırmamaq üçün mümkün olan ən aşağı minSdk (əksər hallarda 21) göstərmək tövsiyə olunur. Kitabxana API 29+ tələb edirsə, potensial istifadəçilərin ~28%-ni itirir.

Multi-modul layihələr müxtəlif modullar üçün müxtəlif minSdkVersion-a malik ola bilər. Məsələn, :core:network modulu minSdk 26, :feature:camera modulu isə minSdk 29 ola bilər (müəyyən tələblərlə CameraX səbəbindən). Google Play əsas :app modulunun minSdk-inin bütün asılı modulların minSdk-indən aşağı və ya bərabər olmasını tələb edir. Praktikada bir tətbiqin bütün modulları adətən dəstəyi sadələşdirmək üçün eyni minSdk-ə malikdir.

// build.gradle.kts — aşağı minSdk-li kitabxana modulu
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // Maksimum əhatə üçün minimum
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, backportlar əlavə edir
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

minSdk = 21 olan kitabxana modulu cihazların 97%-i ilə uyğundur və istehlakçıları məhdudlaşdırmır. Kitabxana 21-dən yuxarı API istifadə edərsə, tərtibatçı icra vaxtı yoxlamaları əlavə etməli və ya müvafiq metodlarda @RequiresApi qeyd etməlidir. AndroidX Core KTX (minSdk 21) Context, Bundle, Locale və digər sistem sinifləri üçün backportlar təmin edir ki, kitabxana aşağı minSdk saxlasın.

minSdkVersion seçimində tipik səhvlər

minSdk seçimində səhvlər minlərlə quraşdırmaya və ya həftələrlə əlavə inkişafa başa gələ bilər. Birinci tipik səhv — Distribution Dashboard təhlili olmadan minSdk-ni layihə şablonundan kopyalamaq. Bir çox tərtibatçı Android Studio Template-dən minSdk = 21 qoyur, halbuki onların auditoriyası üçün minSdk 26 kifayət edər və koddakı SDK_INT yoxlamalarının sayını azaldardı.

İkinci səhv — çox yüksək minSdk bazarı nəzərə almadan. Beynəlxalq tətbiq üçün minSdk = 31 (Android 12) təyin etsəniz, cihazların ~45%-ni itirirsiniz. Kütləvi auditoriyası olan startup və ya tətbiq üçün bu fəlakətdir. minSdk-ni artırmazdan əvvəl həmişə Distribution Dashboard-ı yoxlayın və əmin deyilsinizsə Google Play Console-da A/B testindən istifadə edin.

Üçüncü səhv — asiılılıqların minSdk-ni nəzərdən qaçırmaq. Yeni kitabxana əlavə edərkən onun minSdk-ni sənədlərdə və ya POM faylında yoxlayın. Firebase ML Kit minSdk 21 tələb edir, bəzi fərdi kamera kitabxanaları minSdk 29 tələb edir. Yeni kitabxana səbəbindən manifest merger production-da çökərsə, düzəliş günlər çəkə bilər.

// Nümunə: API uyğunluğunun icra vaxtında yoxlanılması
fun checkFeatureAvailability(): Boolean {
    // Tipik səhv — SDK_INT yoxlaması olmadan API çağırışı
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — PhotoPicker istifadə edirik
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — MediaStore istifadə edirik
            true
        }
        else -> {
            // API < 29 — ACTION_GET_CONTENT istifadə edirik
            true
        }
    }
}

API Level yoxlamalarının düzgün arxitekturası — minSdk-dən compileSdk-ə qədər bütün mümkün dəyərləri əhatə edən diapazonlarla when ifadəsidir. Əsas qayda: X səviyyəli API-nin hər çağırışı minSdk-dən X-ə qədər API Level-i olan bütün cihazlar üçün VERSION.SDK_INT yoxlaması ilə qorunmalıdır. lint yoxlanılmamış çağırışları aşkar etməyə kömək edir, lakin dinamik kod üçün tam əhatəyə zəmanət verə bilməz.