API Level: nedir, API sürümleri ve targetSdk

API Level Android Nedir?

API Level Android, Android Framework API'sinin her genel sürümüne atanan bir tam sayı tanımlayıcıdır. İlk sürüm Android 1.0, API Level 1'e sahipti, 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. Her yeni API Level, yeni sınıflar, yöntemler, sabitler, izinler ekleyebilir ve mevcut olanların davranışını değiştirebilir.

API Level, her sürümle kesin olarak 1 artmaz. Örneğin, Android 4.4W (Wear) API 20'ye sahipken, Android 5.0 API 21'e sahiptir. Boşluklar, dahili yinelemeler ve Wear OS cihazlarıyla ilgilidir. Geliştirici için sürüm adını (KitKat, Lollipop, Tiramisu) değil, API Level'ini bilmek önemlidir — kodda uyumluluk kontrolleri için kullanılan budur.

API Level'in temel amacı geriye dönük uyumluluktur. API 34'e karşı derlenmiş bir uygulama, API 34 ve altındaki cihazlarda çalışabilir (kontrolsüz yeni API'ler kullanmıyorsa). Android Runtime (ART), sistem düzeyinde API çağrılarını kontrol eder ve uygulamanın targetSdkVersion'ına bağlı olarak davranış değişiklikleri uygular.

Android API Level'ı Nasıl İşler

Bir uygulama yüklenirken, PackageManager cihazın API Level'inin AndroidManifest.xml'deki minSdkVersion >= olup olmadığını kontrol eder. Koşul karşılanmazsa — yükleme "App not installed" mesajıyla engellenir. Çalışma zamanında, Android Runtime daha yüksek API Level gerektiren API çağrılarını izler ve yöntem mevcut sürümde yoksa NoSuchMethodError veya UnsatisfiedLinkError oluşturur.

minSdk, targetSdk, compileSdk: Farklılıklar ve Her Parametrenin Rolü

build.gradle dosyasında (Module: app), geliştirici üç API Level parametresi belirtir: minSdkVersion, targetSdkVersion ve compileSdkVersion. Bunları karıştırmak, yeni başlayan Android geliştiricilerinin en yaygın hatalarından biridir. Her parametre, uyumluluğun farklı bir yönünden sorumludur ve değerleri tutarlı olmalıdır.

minSdkVersion

minSdkVersion, uygulamanın yüklenip çalıştırılabileceği minimum API Level'dir. minSdk'den düşük API Level'ine sahip cihazlar, uygulamayı Google Play'de görmez ve yükleyemez. Değer, hedef kitleye göre seçilir: minSdk 21 (Android 5.0) cihazların %97'sini kapsar, minSdk 26 (Android 8.0) — yaklaşık %85, minSdk 31 (Android 12) — yaklaşık %55 (Android Studio Distribution Dashboard, 2026 verileri). minSdk ne kadar düşükse, kapsam o kadar geniş, ancak geriye dönük uyumluluk kodu o kadar fazladır.

targetSdkVersion

targetSdkVersion, uygulamanın test edildiği API Level'dir. Android, davranış değişikliklerini uygulamak için targetSdk kullanır: uygulama targetSdk 33 belirtirse, sistem API 33'te tanıtılan tüm davranış değişikliklerini etkinleştirir. targetSdk 31 ise, sistem API 32-33 değişikliklerini uygulamaz, eski davranışla uyumluluğu korur. Bu, güvenlik için en önemli parametredir: Google Play, targetSdk'nin mevcut API Level'den 1 yıldan eski olmamasını şart koşar.

compileSdkVersion

compileSdkVersion, kodun derlendiği Android SDK sürümüdür. Derleme zamanında hangi API'lerin kullanılabilir olduğunu belirler. compileSdk, targetSdk >= olmalı ve ideal olarak en son kararlı API Level'e eşit olmalıdır. compileSdk'yı yükseltmek çalışma zamanı davranışını etkilemez — yalnızca derleyici için yeni API'lerin kullanılabilirliğini etkiler. compileSdk yükseltildikten sonra, kod kullanımdan kaldırılan API'ler ve yeni izin gereksinimleri açısından kontrol edilmelidir.

// build.gradle.kts — API Level yapılandırma örneği
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 örneğinde, compileSdk = 36 (yazım anında en son), targetSdk = 36, minSdk = 26 (Android 8.0). compileSdk 36, tüm Android 16 API'lerine erişim sağlar. targetSdk 36, tüm Android 16 davranış değişikliklerini etkinleştirir. minSdk 26, cihazların ~%85'ini kapsar. AndroidX Activity KTX ve AppCompat, fragmentler ve temalar için geriye dönük uyumluluk sağlar.

AndroidManifest.xml

minSdk ve targetSdk parametreleri AndroidManifest.xml içinde de belirtilebilir, ancak modern projeler build.gradle kullanır — Gradle değerleri manifesti geçersiz kılar. Manifestte, Gradle derleme yapılandırmasını kullanmayan kitaplıklar ve modüller için belirtmek yararlı olabilir.

Davranış Değişiklikleri: targetSdk Uygulama Davranışını Nasıl Etkiler

Davranış değişiklikleri, yalnızca targetSdk >= belirli bir API Level olan uygulamalara uygulanan Android sistemi çalışma şeklindeki değişikliklerdir. Her yeni Android sürümü, güncellenmezlerse mevcut uygulamaları bozabilecek davranış değişiklikleri getirir. Bu, Android'in önemli bir güvenlik mekanizmasıdır: eski uygulamalar eskisi gibi çalışmaya devam eder, yenileri mevcut kuralları takip eder.

Sürümlere Göre Başlıca Davranış Değişiklikleri

Android 10 (API 29) — Scoped Storage: targetSdk 29+ olan uygulamaların ortak dosya sistemine doğrudan erişimi yoktur, yalnızca MediaStore, SAF veya kendi depolama alanı aracılığıyla. Android 11 (API 30) — Package Visibility: paket filtresi, uygulamalar yalnızca etkileşimde bulundukları yüklü paketleri görür. Android 12 (API 31) — Foreground Service Notification: tüm ön plan hizmetleri, başlatmadan sonraki 10 saniye içinde bir bildirim göstermek zorundadır. Android 13 (API 33) — POST_NOTIFICATIONS: push bildirimleri için çalışma zamanı izni. Android 14 (API 34) — Foreground Service Types: manifestte ön plan hizmet türünün zorunlu bildirimi.

// Android 13 (API 33) davranış değişikliklerini işleme: 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 izni yalnızca API 33+ ile çalışır
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            return  // API 33 altında izin gerekmez
        }

        when {
            ContextCompat.checkSelfPermission(
                activity,
                Manifest.permission.POST_NOTIFICATIONS
            ) == PackageManager.PERMISSION_GRANTED -> {
                // İzin zaten verildi, bildirimler gönderilebilir
                showNotification(activity)
            }

            activity.shouldShowRequestPermissionRationale(
                Manifest.permission.POST_NOTIFICATIONS
            ) -> {
                // İzne neden ihtiyaç duyulduğuna dair açıklama göster
                activity.showRationale()
            }

            else -> {
                // İzin iste
                activity.requestPermissionLauncher.launch(
                    Manifest.permission.POST_NOTIFICATIONS
                )
            }
        }
    }

    private fun showNotification(context: Context) {
        // Bildirim oluştur ve göster
        val notification = android.app.Notification.Builder(context, "default_channel")
            .setSmallIcon(android.R.drawable.ic_dialog_info)
            .setContentTitle("Bildirim")
            .setContentText("Yeni mesaj")
            .build()
        val manager = context.getSystemService(Context.NOTIFICATION_SERVICE)
            as android.app.NotificationManager
        manager.notify(1, notification)
    }
}

// Activity'de requestPermissionLauncher'ı kaydet
class MainActivity : ComponentActivity() {
    val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted: Boolean ->
        if (isGranted) {
            // İzin verildi
        }
    }

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

Kotlin'de POST_NOTIFICATIONS işleme örneği: Build.VERSION.SDK_INT >= TIRAMISU'yu kontrol etme, ActivityResultContracts.RequestPermission aracılığıyla çalışma zamanı izni isteme, sonucu bir geri çağırmada işleme. Bu izin olmadan, targetSdk 33+ olan bir uygulama push bildirimleri gösteremez. API 33'ün altında izin gerekmez — kontrol kodu, kullanılamayan API'lerin çağrılmasını önler.

Scoped Storage (Android 10+)

Scoped Storage en önemli davranış değişikliklerinden biridir. API 29'dan (targetSdk 29+) itibaren, uygulama Pictures, Downloads, Music ve Documents dizinlerine doğrudan dosya erişimi elde edemez. Bunun yerine, medya için MediaStore, rastgele dosyalar için SAF (Storage Access Framework) ve kendi depolaması için getExternalFilesDir() kullanılır. İstisna, Google Play onayı gerektiren MANAGE_EXTERNAL_STORAGE iznine sahip uygulamalardır.

Google Play'in API Level ve targetSdk Gereksinimleri

Google Play, uygulama yayınlamak için targetSdkVersion'da zorunlu gereksinimler belirler. Ağustos 2024'ten itibaren Google Play, targetSdkVersion >= API 33 (Android 13) gerektirir. Her yıl eşik yükselir: yeni uygulamalar ve güncellemeler, mevcut ana API Level'den 1 yıldan eski olmayan targetSdk belirtmelidir. Gereksinimin ihlali, yayının engellenmesine ve uygulamanın mağazadan kaldırılmasına yol açar.

Google Play Neden Gereksinimleri Sıkılaştırıyor

Ana neden güvenliktir. Her yeni Android API Level, saldırı vektörlerini kapatan davranış değişiklikleri getirir: Scoped Storage (API 29) dosya hırsızlığını önler, POST_NOTIFICATIONS (API 33) spam bildirimlere karşı korur, Foreground Service Types (API 34) gizli arka plan hizmetlerini sınırlar. Düşük targetSdk'ye sahip uygulamalar bu korumaları alamaz ve kullanıcılar için tehdit oluşturur. Google Play, modern cihazlarda güncel olmayan uygulamalara izin veremez.

Gereksinimlere Uygunluğun Kontrolü

Google Play Console, APK/AAB yüklerken targetSdkVersion'ı kontrol eder. targetSdk gerekenin altındaysa — konsol, "Your app currently targets API level X and must target at least API level Y" mesajıyla yayını engeller. Geliştirici build.gradle'ı güncellemeli, uygulamayı yeniden derlemeli, davranış değişikliklerini test etmeli ve yeniden yüklemelidir. AAB formatı tüm yeni yayınlar için önerilir (Ağustos 2021'den itibaren zorunludur).

Kodda API Level Kontrolü: Build.VERSION.SDK_INT

Build.VERSION.SDK_INT, uygulamanın çalıştığı cihazın API Level'ini içeren statik bir tam sayı sabitidir. Çalışma zamanı Android sürüm kontrolleri için birincil araçtır. Build.VERSION_CODES, her API Level için adlandırılmış sabitler içerir: VERSION_CODES.TIRAMISU (33), VERSION_CODES.UPSIDE_DOWN_CAKE (34), VERSION_CODES.VANILLA_ICE_CREAM (35). if (SDK_INT >= VERSION_CODES.TIRAMISU) ile karşılaştırma standart desendir.

// Android kodunda API Level kontrolü örnekleri
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.drawable.AdaptiveIconDrawable

class ApiLevelHelper {

    // 1. Temel API Level kontrolü
    fun isAtLeastTiramisu(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU  // 33
    }

    // 2. Kontrollü uyarlanabilir API çağrısı
    fun getAdaptiveIcon(drawable: android.graphics.drawable.Drawable):
            android.graphics.drawable.Drawable? {
        // AdaptiveIconDrawable yalnızca API 26 (Android 8) ile kullanılabilir
        if (VERSION.SDK_INT >= VERSION_CODES.O) {
            return AdaptiveIconDrawable(drawable, null)
        }
        return drawable  // eski cihazlar için fallback
    }

    // 3. POST_NOTIFICATIONS izin kontrolü (yalnızca API 33+)
    fun canRequestNotificationPermission(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.TIRAMISU
    }

    // 4. API Level'e göre resim sağlayıcı seçimi
    fun getImagePickerProvider(): String {
        return when {
            VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
                // API 34+ PhotoPicker kullanır
                "photo_picker"
            }
            VERSION.SDK_INT >= VERSION_CODES.KITKAT -> {
                // API 19+ Intent ACTION_OPEN_DOCUMENT kullanır
                "open_document"
            }
            else -> {
                // Eski: ACTION_GET_CONTENT (tüm sürümler)
                "get_content"
            }
        }
    }

    // 5. @TargetApi ile Java tarzı kontrol (geriye dönük uyumluluk için)
    @Suppress("DEPRECATION")
    fun checkLegacyStorage(): Boolean {
        // Scoped Storage davranışı SDK_INT'a değil, targetSdk'a bağlıdır
        return VERSION.SDK_INT < VERSION_CODES.Q  // Android 10
    }

    // 6. Analitik için derleme bilgisi
    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
        )
    }
}

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

ApiLevelHelper sınıfı, tüm ana API Level kontrol desenlerini gösterir: SDK_INT >= VERSION_CODES ile isAtLeastTiramisu, eski sürümler için fallback ile getAdaptiveIcon, when çoklu dallanma ile getImagePickerProvider, analitik için getDeviceApiInfo. Ana kural, SDK_INT'yi kontrol etmeden yeni API'leri çağırmamaktır, aksi takdirde uygulama eski cihazlarda NoSuchMethodError ile çökecektir.

ANT (Android New API) ve lint

Android Studio, minSdkVersion üzerinde API kullanımı konusunda uyaran statik analizör lint'i içerir. SDK_INT kontrolü olmadan bir yöntem çağrılırsa, lint bunu bir hata olarak vurgular: "Call requires API level 34 (current min is 26)". Çözümler: yönteme @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) eklemek veya SDK_INT'nin if kontrolü. @TargetApi kullanımdan kaldırılmış bir ek açıklamadır, @RequiresApi önerilir.

API Level ve Android Sürümleri Eşleşme Tablosu

API Level tablosu, geliştirici için bir referans aracıdır. Cihazın API Level'ini bilerek, Android sürümünü ve mevcut özellikleri belirleyebilirsiniz. Tablo, API Level 1'den (2008) API Level 36'ya (2025) kadar tüm önemli Android sürümlerini listeler. Kod adları (Cupcake, Donut, Tiramisu, VanillaIceCream) Google içinde ve VERSION_CODES'ta kullanılır.

Tablo: Davranış Değişiklikleri için Eşik API Level'leri

Aşağıdaki tablo, targetSdk yükseltildiğinde geriye dönük uyumluluğu bozan davranış değişiklikleri getiren ana API Level'leri gösterir: