minSdkVersion: nedir ve minimum Android sürümü nasıl seçilir

Android'de minSdkVersion Nedir?

minSdkVersion, build.gradle dosyasında uygulama kurulumu için minimum Android API Düzeyini belirten bir tamsayı parametresidir. Cihazın API Düzeyi belirtilen değerin altındaysa, PackageManager kurulumu engeller ve Google Play Store, bu cihaz için arama sonuçlarından uygulamayı gizler. minSdkVersion, derleme sırasında <uses-sdk android:minSdkVersion> etiketi aracılığıyla AndroidManifest.xml dosyasına yazılır ve her kurulumda kontrol edilir.

minSdkVersion değeri, hedef kitleye erişim ile yeni API'lere erişim arasında bir denge unsurudur. minSdk ne kadar düşükse, özellikle eski Android akıllı telefonların popüler olduğu gelişmekte olan bölgelerde, o kadar fazla cihaz uygulamayı kurabilir. minSdk ne kadar yüksekse, o kadar az geriye dönük uyumluluk kodu gerekir ve çalışma zamanı kontrolleri olmadan daha fazla modern API kullanılabilir. Android Jetpack ve AndroidX kütüphaneleri, birçok yeni API'nin geri uyumluluk sürümlerini eski Android sürümlerine sağlayarak, işlevsellik kaybı olmadan daha düşük bir minSdk seçilmesine olanak tanır.

minSdkVersion, geliştirmenin tüm aşamalarını etkiler: statik analiz (lint, uyarılar için minSdk'yi kullanır), bağımlılık uyumluluğu (kütüphaneler kendi minSdk'lerini gerektirebilir), test (minSdk'li cihazlarda test yapmak gerekir) ve Google Play Console (hedef kitleye erişim, minSdk'ye göre hesaplanır). minSdkVersion'ı değiştirmek, proje kurulumundaki en önemli kararlardan biridir çünkü kodu, testleri ve kullanıcı tabanını etkiler.

minSdkVersion Nerede Belirtilir

Build.gradle.kts (Kotlin DSL), Android projelerinde modern standarttır. minSdk parametresi, modül düzeyinde defaultConfig bloğunda ayarlanır. Değer, farklı derleme türleri ve ürün çeşitleri için geçersiz kılınabilir, bu da ana değeri değiştirmeden daha düşük API'lerde test yapılmasına olanak tanır.

// build.gradle.kts — temel minSdk yapılandırması
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"
    }

    // Farklı çeşitler için minSdk'nin geçersiz kılınması
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

Örnekte, minSdk = 26, Android 8.0 Oreo'ya karşılık gelir. Bu, 2026'da popüler bir değerdir: Android Studio Distribution Dashboard'a göre cihazların yalnızca ~%15'ini hariç tutar. compileSdk = 36, tüm Android 16 API'lerine erişim sağlar ve targetSdk = 36, en son sürümün davranışsal değişikliklerini içerir. Hata ayıklama derlemeleri için, eski öykünücülerde test yapmak amacıyla minSdk düşürülebilir.

minSdkVersion Nasıl Seçilir: Faktörler ve Strateji

minSdkVersion Seçimi, hedef kitle, API gereksinimleri ve kütüphane ekosisteminin analizine dayanan stratejik bir karardır. Tüm projeler için tek bir doğru değer yoktur. 2026'da Android Studio, yeni projeler için temel seviye olarak minSdk = 26'yı (Android 8.0) önerir, ancak B2B uygulamaları veya kurumsal çözümler için daha düşük veya daha yüksek değerler kabul edilebilir.

minSdkVersion Seçim Faktörleri

İlk faktör Distribution Dashboard'dur. Android Studio, Google Play verilerine dayalı olarak API Düzeyine göre aktif cihaz istatistikleri sağlar ve aylık olarak güncellenir. minSdkVersion, hedef pazarın aktif cihazlarının en az %90-95'ini kapsamalıdır. Afrika ve Güneydoğu Asya'da kitlesi olan uluslararası uygulamalar için, eski cihazların yüksek payı nedeniyle minSdk 21'e (Android 5.0) düşürülmelidir.

İkinci faktör bağımlılık gereksinimleridir. Her kütüphanenin manifest dosyasında belirtilen kendi minSdkVersion'ı vardır. Bir kütüphane minSdk 29 gerektiriyor ve uygulama minSdk 26 gerektiriyorsa, derleme manifest birleştirme hatasıyla başarısız olur. Modern Google Play Services kütüphaneleri minSdk 21'e, Firebase minSdk 21'e, çoğu Jetpack kütüphanesi minSdk 21 veya 26'ya ve Compose BOM minSdk 21'e sahiptir. Compose için minimum eşik API 21'dir.

Üçüncü faktör gerekli API'lerdir. Uygulamanın temel işlevselliği yalnızca belirli bir düzeyden itibaren kullanılabilen bir API gerektiriyorsa (örneğin, PhotoPicker — API 34, Predicted Navigation — API 35), bu minSdk'yi yükseltmeyi haklı çıkarabilir. Bununla birlikte, düşük bir minSdk'yi korumak için daha sık olarak AndroidX geri uyumluluk sürümleri (Activity Result API, NotificationCompat) ve çalışma zamanı kontrollerinin bir kombinasyonu kullanılır.

Adım Adım Seçim Stratejisi

Adım 1: Android Studio'yu açın, File → New Project ve sihirbazda önerilen minSdk'yi kontrol edin. Adım 2: Android Studio'da Distribution Dashboard'ı kontrol edin (View → Tool Windows → App Inspection → Distribution Dashboard). Adım 3: Proje bağımlılıklarını analiz edin — derlemeyi çalıştırın ve manifest birleştirme çakışmalarını düzeltin. Adım 4: Geri uyumluluk sürümleri olmadan hangi API seviye X'in gerçekten kullanıldığını değerlendirin. Adım 5: Hedef kitlenin %90+'ını kapsayan ve tüm bağımlılıklarla uyumlu minimum değer olarak minSdk'yi ayarlayın.

Cihaz Kapsamı: API Düzeyi Dağılımı (2026)

API Düzeyine göre cihaz dağılımı her çeyrekte değişen dinamik bir ölçüttür. Haziran 2026 itibarıyla Android Studio Distribution Dashboard'a göre, aktif Android cihazlarının yaklaşık %85'i API 26 (Android 8.0) ve üzerinde, %72'si API 29 (Android 10) ve üzerinde ve %55'i API 31 (Android 12) ve üzerinde çalışmaktadır. Çin pazarı, birçok Huawei cihazında Google Play Services'in bulunmaması nedeniyle kendi istatistiklerine sahiptir.

GMS cihazları (Google Mobile Services) daha hızlı güncellenir: üreticiler için Google Play'in zorunlu gereksinimleri sayesinde API 31+ oranı %68'e ulaşır. GMS olmayan cihazlar (Huawei, Honor, bazı Çin markaları) daha eski bir dağılıma sahiptir: API 31+ oranı yaklaşık %35'tir. Uygulamanız uluslararası pazara yönelikse, küresel istatistiklere güvenin. Çin'e yönelikse, GMS olmayan segmenti göz önünde bulundurun.

Sonuç: uluslararası bir uygulama için minSdk 26, minimum geriye dönük uyumluluk maliyetiyle cihazların %85'ini kapsar. Gelişmekte olan bölgelerde kitlesi olan uygulamalar için minSdk 21 (%97 kapsam) haklıdır ancak eski API'lerle çalışmak için daha fazla kod gerektirecektir. Kontrollü cihaz filosuna sahip kurumsal uygulamalar için minSdk 31'i ayarlayabilir ve yedek kodu tamamen ortadan kaldırabilirsiniz.

Geriye Dönük Uyumluluk: AndroidX, lint ve @RequiresApi

Geriye dönük uyumluluk, düşük bir minSdkVersion ile ana zorluktur. AndroidX (önceden Support Library), modern API'lerin geri uyumluluk sürümlerini eski Android sürümlerine sağlar: Material Design için AppCompatActivity, FragmentManager, Loader, NotificationCompat, PreferenceFragmentCompat ve düzinelerce başka bileşen. Yerel API'ler yerine AndroidX eşdeğerlerini kullanmak, uyumluluğa doğru ilk adımdır.

lint (Android Studio'nun statik analizörü), minSdkVersion'ın üzerindeki API çağrıları için kodu tarar. Bir yöntem, minSdk'den daha yüksek bir API Düzeyinde @RequiresApi ile ek açıklamaya sahipse ve kontrol olmadan çağrılırsa, lint bir hata vurgular. Uyarıyı bastırmak için, yöntemde @SuppressLint("NewApi") ek açıklamasını veya tüm işlevde @RequiresApi(Build.VERSION_CODES.TIRAMISU) kullanın. Çalışma zamanı kontrolleri (Build.VERSION.SDK_INT aracılığıyla), eski cihazlarda yeni API'leri güvenle çağırmanın ana mekanizmasıdır.

// Geriye dönük uyumluluk örneği: PhotoPicker (API 34+) ve yedek
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) — herhangi bir API Düzeyinde çalışır
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker yalnızca API 34'ten itibaren kullanılabilir
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // PhotoPicker kullanımı (API 34+)
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // Yedek: GetContent (tüm sürümlerde çalışır)
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // Bu yöntem API'de çağrılamaz < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

ImagePickerActivity sınıfı, üç düzeyde geriye dönük uyumluluk gösterir. AndroidX'teki Activity Result API tüm API Düzeylerinde çalışır, bu nedenle temel görüntü seçimi minSdk'ye bağlı değildir. PhotoPicker (ACTION_PICK_IMAGES) yalnızca API 34'ten itibaren kullanılabilir ve GetContent'e yedekleme ile SDK_INT kontrolü altında çağrılır. usePhotoPickerOnly yöntemi @RequiresApi ile işaretlenmiştir — lint, kontrol olmadan çağrılmasına izin vermez. AndroidX'teki AppCompat, temayı, parçaları ve animasyonları otomatik olarak işletim sistemi sürümüne uyarlar.

Kütüphanelerde ve Modüllerde minSdkVersion

Kütüphanelerin (AAR, JAR) ayrıca manifest dosyalarında belirtilmiş bir minSdkVersion'ı vardır. Bir kütüphane bağlanırken Gradle uyumluluğu kontrol eder: kütüphanenin minSdk'si uygulamanın minSdk'sinden yüksekse, derleme bir hatayla başarısız olur. Genel kütüphaneler için, tüketicileri sınırlamamak adına mümkün olan en düşük minSdk'nin (çoğu durumda 21) belirtilmesi önerilir. Bir kütüphane API 29+ gerektiriyorsa, potansiyel kullanıcılarının ~%28'ini kaybeder.

Çok modüllü projeler, farklı modüller için farklı minSdkVersion değerlerine sahip olabilir. Örneğin, :core:network modülü minSdk 26'ya sahipken, :feature:camera modülü minSdk 29'a (belirli gereksinimleri olan CameraX nedeniyle) sahip olabilir. Google Play, ana :app modülünün minSdk'sinin tüm bağımlı modüllerin minSdk'sinden düşük veya eşit olmasını gerektirir. Pratikte, aynı uygulamanın tüm modülleri, bakımı kolaylaştırmak için genellikle aynı minSdk'ye sahiptir.

// build.gradle.kts — düşük minSdk'li kütüphane modülü
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        minSdk = 21  // Maksimum kapsam için minimum
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21, geri uyumluluk sürümleri ekler
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

minSdk = 21 olan bir kütüphane modülü, cihazların %97'siyle uyumludur ve tüketicileri sınırlamaz. Kütüphane 21'in üzerinde API'ler kullanıyorsa, geliştiricinin çalışma zamanı kontrolleri eklemesi veya ilgili yöntemlerde @RequiresApi belirtmesi gerekir. AndroidX Core KTX (minSdk 21), Context, Bundle, Locale ve diğer sistem sınıfları için geri uyumluluk sürümleri sağlayarak kütüphanenin düşük bir minSdk'yi korumasına olanak tanır.

minSdkVersion Seçerken Yaygın Hatalar

minSdk seçiminde yapılan hatalar binlerce kuruluma veya haftalarca süren ek geliştirmeye mal olabilir. İlk yaygın hata, Distribution Dashboard'ı analiz etmeden bir proje şablonundan minSdk'yi kopyalamaktır. Birçok geliştirici, Android Studio Şablonundan minSdk = 21'i bırakır, oysa minSdk 26 kitleleri için yeterli olacak ve kod içindeki SDK_INT kontrollerinin sayısını azaltacaktır.

İkinci hata, pazarı dikkate almadan çok yüksek bir minSdk belirlemektir. Uluslararası bir uygulama için minSdk = 31 (Android 12) ayarlarsanız, cihazların ~%45'ini kaybedersiniz. Bir startup veya geniş kitleli bir uygulama için bu bir felakettir. minSdk'yi yükseltmeden önce her zaman Distribution Dashboard'ı kontrol edin ve emin değilseniz Google Play Console'da A/B testi kullanın.

Üçüncü hata, bağımlılıkların minSdk'sini görmezden gelmektir. Yeni bir kütüphane eklerken, belgelerinde veya POM dosyasında minSdk'sini kontrol edin. Firebase ML Kit, minSdk 21 gerektirir, bazı özel kamera kütüphaneleri minSdk 29 gerektirir. Yeni bir kütüphane nedeniyle üretimde manifest birleştirme başarısız olursa, düzeltme günler sürebilir.

// Örnek: çalışma zamanında API uyumluluk kontrolü
fun checkFeatureAvailability(): Boolean {
    // Tipik hata — SDK_INT kontrolü olmadan API çağrısı
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — PhotoPicker kullanın
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — MediaStore kullanın
            true
        }
        else -> {
            // API < 29 — ACTION_GET_CONTENT kullanıyoruz
            true
        }
    }
}

API Düzeyi kontrolleri için doğru mimari, minSdk'den compileSdk'ye kadar tüm olası değerleri kapsayan aralıklarla bir when ifadesidir. Temel kural: X seviyesindeki herhangi bir API çağrısı, minSdk'den X'e kadar API Düzeyine sahip tüm cihazlar için bir VERSION.SDK_INT kontrolü ile korunmalıdır. lint, kontrol edilmeyen çağrıları tespit etmeye yardımcı olur, ancak dinamik kod için tam kapsamı garanti edemez.