targetSdkVersion: Temel kavramlar, behavioural changes ve Google Play

Android'de targetSdkVersion nedir?

targetSdkVersion build.gradle dosyasında uygulamanın test edildiği API Level'ı bildiren bir tam sayı parametresidir. Android sistemi bu parametreyi kullanarak çalışma zamanında uygulamaya hangi behavioural changes'ların uygulanacağına karar verir. targetSdkVersion = 33 ise Android, API 33'e kadar tanıtılan tüm behavioural changes'ları uygular ancak API 34+ değişikliklerini uygulamaz. targetSdkVersion = 34 ise — API 34'e kadar olan değişiklikler uygulanır ve bu böyle devam eder.

targetSdkVersion ve minSdkVersion arasındaki temel fark, etki mekanizmasıdır. minSdk kurulum sırasında bir kez kontrol edilir ve koşul karşılanmazsa kurulumu engeller. targetSdkVersion, uygulamanın hangi Android sürümünde çalıştığına bakılmaksızın her cihazda sistemin çalışma zamanı davranışını etkiler. targetSdk 31 olan aynı uygulama, Android 13, 14 ve 15'te farklı davranacaktır çünkü 31'in üzerindeki behavioural changes'lar devre dışıdır.

targetSdkVersion mekanizması, Android'de yerleşik bir geriye dönük uyumluluk aracıdır. Olmasaydı, her işletim sistemi güncellemesi binlerce eski uygulamayı bozardı. Google bu mekanizmayı Android 2.1'de (API Level 7) tanıttı ve o zamandan beri mevcut uygulamaları bozmadan yeni güvenlik, gizlilik ve kaynak yönetimi kurallarını tanıtmak için standart bir yöntem olarak kullanıyor.

// build.gradle.kts — defaultConfig'ta targetSdkVersion
android {
    namespace = "com.example.myapp"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36   // Android 16'da test edildi
        versionCode = 1
        versionName = "1.0.0"
    }
}

// Kodda mevcut targetSdk'yi kontrol etme
fun isUsingScopedStorage(): Boolean {
    // Context.getApplicationInfo().targetSdkVersion, uygulamanın targetSdk'sini içerir
    return context.applicationInfo.targetSdkVersion >= VERSION_CODES.Q
}

Örnekte, targetSdk = 36 Android 16'nın tüm behavioural changes'larını etkinleştirir. Kod, context.applicationInfo.targetSdkVersion aracılığıyla targetSdkVersion'ı kontrol eder — bu, hangi uyumluluk modunun etkin olduğunu dinamik olarak belirlemeye olanak tanır. Yardımcı işlev, çağıran uygulamanın targetSdk'sine uyum sağlaması gereken kütüphaneler için kullanışlıdır.

Behavioural Changes: targetSdk uygulamayı nasıl etkiler

Behavioural changes, targetSdkVersion >= belirli bir API Level olan uygulamalara uygulanan Android sistem davranışı değişiklikleridir. Her yeni büyük Android sürümü behavioural changes'lar sunar ve bir uygulama targetSdk'yi güncellemezse bu değişiklikler yürürlüğe girmez. Bu mekanizma, geliştiricilerin uygulamalarını yeni bir işletim sistemi sürümüyle eşzamanlı olarak değil, kendi hızlarında güncellemelerine olanak tanır.

Scoped Storage (API 29) en önemli behavioural changes'lardan biridir. targetSdk 29+ olan uygulamalar, Pictures, Downloads, Music, Documents gibi paylaşılan dizinlere doğrudan Dosya erişimi alamaz. Bunun yerine, medya için MediaStore, rastgele dosyalar için SAF (Storage Access Framework) ve özel depolama için getExternalFilesDir() kullanılır. targetSdk 28 ve altındaki eski uygulamalar eski Full Storage Access ile çalışmaya devam eder, ancak bu bir güvenlik riski oluşturur.

POST_NOTIFICATIONS (API 33), bildirim göndermek için bir çalışma zamanı iznidir. targetSdk 33+ olan uygulamalar, standart iletişim kutusu aracılığıyla kullanıcıdan Manifest.permission.POST_NOTIFICATIONS iznini talep etmelidir. İzin verilmezse, NotificationManager.silent() kullanıcıya bildirim göstermez. Android 13+'da bu izin olmadan push bildirimleri ve yerel bildirimler görüntülenmez, bu da kullanıcı etkileşimini önemli ölçüde azaltabilir.

Mevcut targetSdk nasıl kontrol edilir

targetSdkVersion değeri ADB aracılığıyla elde edilebilir: adb shell dumpsys package com.example.myapp | grep targetSdk komutu targetSdk=34 çıktısını verir. Kodda, context.getApplicationInfo().targetSdkVersion bir tam sayı döndürür. Analiz için, her oturumda hangi behavioural changes'ların gerçekten etkin olduğunu anlamak için targetSdk'yi android.os.Build.VERSION.SDK_INT ile birlikte günlüğe kaydetmek faydalıdır.

Google Play'in targetSdkVersion gereksinimleri (2026)

Google Play, yayınlanan tüm uygulamalar için zorunlu targetSdkVersion gereksinimleri belirler. Ağustos 2024'ten itibaren minimum targetSdk = 33 (Android 13). Ağustos 2025'ten itibaren targetSdk = 34. Ağustos 2026'dan itibaren Google'ın targetSdk = 35 (Android 15) talep etmesi bekleniyor. Yeni uygulamalar ve mevcut uygulamaların güncellemeleri bu gereksinimlere uymalıdır, aksi halde konsol yayınlamayı engeller. Bu bir Google Play politikasıdır, Android Runtime kısıtlaması değildir: targetSdk 34 olan bir uygulama Android 16'da çalışabilir ancak Play Store'da yayınlanamaz.

Android App Bundle (AAB), Ağustos 2021'den itibaren zorunlu yayınlama biçimidir. APK artık Google Play'de kabul edilmemektedir (150 MB'dan büyük uygulamalar ve bazı eski projeler hariç). AAB biçimi, Google'ın her API Level ve ekran yoğunluğu için optimize edilmiş APK'lar oluşturmasına olanak tanır ve indirme boyutunu %15-30 oranında azaltır. targetSdk'yi kontrol etmek için Google Play, AAB manifest dosyasını analiz eder ve uygun değilse gerekli minimum değerle bir hata verir.

Google Play Console, targetSdkVersion değerini yalnızca yeni bir AAB yüklerken değil, mevcut bir uygulamayı güncellerken de kontrol eder. Uygulamanızın targetSdk'si 33 ise ve Google minimum eşiği 34'e yükseltirse — targetSdk'yi yükseltinceye kadar hiçbir güncelleme yayınlayamazsınız. Uzun süredir güncellenmeyen uygulamalar için Google Play, bunları otomatik olarak yayından kaldırabilir (unpublish).

targetSdkVersion hatasız nasıl güncellenir

targetSdkVersion'ı güncellemek yalnızca build.gradle dosyasında bir sayıyı değiştirmek değildir. Kod önceden hazırlanmazsa her behavioural change mevcut işlevselliği bozabilir. Özellikle uygulama büyükse ve birçok sistem API'si kullanıyorsa, Google Play son teslim tarihinden 3-6 ay önce hazırlığa başlanması önerilir.

Adım adım süreç: Adım 1 — Android Developers belgelerinde ("Behavioural Changes by API Level" sayfası) yeni API Level için behavioural changes'ları inceleyin. Adım 2 — targetSdk-update dalı oluşturun ve targetSdk'yi yeni değere değiştirin. Adım 3 — uygulamayı yeni API Level'a sahip bir öykünücü veya cihazda çalıştırın ve değişikliklerle ilgili her işlevi kontrol edin. Adım 4 — hataları düzeltin: izinler ekleyin, dosya işlemeyi değiştirin, manifest dosyasını güncelleyin.

Adım 5 — eski cihazlarda test edin. targetSdk'yi yükseltmek, yeni targetSdk'den daha düşük API Level'a sahip cihazları etkilemez, ancak behavioural changes, API Level >= targetSdk olan tüm cihazlarda uygulanır. targetSdk'yi 33'ten 34'e yükselttiyseniz, API 34+ olan cihazlarda API 34'ün behavioural changes'ları etkinleştirilecektir. API 33 olan cihazlarda hiçbir şey değişmeyecektir.

// targetSdk 35'e hazırlık: Privacy Sandbox
import android.os.Build
import android.os.Build.VERSION_CODES
import com.google.android.gms.ads.identifier.AdvertisingIdClient

class AdsManager {

    fun getAdvertisingId(context: android.content.Context): String? {
        // Privacy Sandbox, API 35'ten itibaren Advertising ID'yi sınırlar
        if (Build.VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+ — tanımlayıcı kullanılamaz, MeasurementManager kullanın
            return null
        }
        return try {
            val adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
            adInfo.getId()
        } catch (e: Exception) {
            null
        }
    }

    // Kontrol: hangi behavioural changes'lar etkin
    fun getActiveChanges(context: android.content.Context): List<String> {
        val sdkInt = Build.VERSION.SDK_INT
        val targetSdk = context.applicationInfo.targetSdkVersion
        return buildList {
            if (sdkInt >= VERSION_CODES.Q && targetSdk >= VERSION_CODES.Q)
                add("ScopedStorage")
            if (sdkInt >= VERSION_CODES.TIRAMISU && targetSdk >= VERSION_CODES.TIRAMISU)
                add("PostNotifications")
            if (sdkInt >= VERSION_CODES.UPSIDE_DOWN_CAKE && targetSdk >= VERSION_CODES.UPSIDE_DOWN_CAKE)
                add("FgsTypes")
        }
    }
}

AdsManager sınıfı, Privacy Sandbox (API 35) için hazırlığı gösterir. Advertising ID, API 35'ten itibaren targetSdk 35+ ile kullanılamaz hale gelir. getActiveChanges işlevi, behavioural changes'ları kontrol etmek için doğru deseni gösterir: cihazın SDK_INT'sini ve uygulamanın targetSdk'sini birlikte kontrol etmek gerekir. Yalnızca her iki koşul da eşleştiğinde değişiklik gerçekten etkindir.

Android 15 (API 35): önemli behavioural changes'lar

Android 15 (API 35, Vanilla Ice Cream), geliştiricilerin targetSdk'yi 35'e güncellerken dikkate alması gereken birkaç kritik behavioural changes sunar. Birincisi — Privacy Sandbox for Android. Bu, Google'ın Advertising ID'yi daha özel API'lerle değiştirme girişimidir: Topics API (kullanıcı ilgi alanları), Protected Audience (yeniden hedefleme) ve Attribution Reporting (dönüşümler). API 35'ten itibaren Advertising ID artık sabit bir tanımlayıcı değildir ve boş bir değer döndürebilir.

İkinci değişiklik — Foreground Service Types (API 34, API 35'te devam ediyor). API 34'ten itibaren, targetSdk 34+ olan her uygulama manifest dosyasında ön plan hizmet türünü belirtmelidir: dataSync, systemExempted, shortService, location, mediaPlayback ve diğerleri. Bu olmadan sistem, ForegroundServiceTypeNotAllowedException hatası oluşturur. API 35'te yeni bir health türü eklenmiş ve mevcut türlerin doğrulaması sıkılaştırılmıştır. Tüm ön plan hizmetleri gözden geçirilmelidir.

Üçüncü değişiklik — SCHEDULE_EXACT_ALARM kısıtlaması. API 35'ten itibaren, targetSdk 35+ olan uygulamalar, açık kullanıcı izni olmadan SCHEDULE_EXACT_ALARM kullanamaz. Sistem bir iletişim kutusu gösterir ve kullanıcının kesin zamanlamayı onaylaması gerekir. Alarmlar ve zamanlayıcılar için bu, UX'te ek bir adım anlamına gelir. Bir alternatif, 10 dakikalık tamponlu kesin olmayan alarmlar kullanmaktır.

// Android 15 (API 35): SCHEDULE_EXACT_ALARM kontrolü
import android.app.AlarmManager
import android.os.Build
import android.provider.Settings

class AlarmScheduler {

    fun canScheduleExactAlarms(context: android.content.Context): Boolean {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            // API 35+: kullanıcı izni gerekli
            val alarmManager = context.getSystemService(
                android.content.Context.ALARM_SERVICE
            ) as AlarmManager
            return alarmManager.canScheduleExactAlarms()
        }
        // API 35 altında — izinsiz hassas alarmlar kullanılabilir
        return true
    }

    fun requestExactAlarmPermission(activity: android.app.Activity) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
            val intent = android.content.Intent(
                Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM
            ).apply {
                data = android.net.Uri.fromParts(
                    "package", activity.packageName, null
                )
            }
            activity.startActivity(intent)
        }
    }
}

Privacy Sandbox ve alarm kısıtlaması, API 35'in en kritik iki behavioural changes'ıdır. Reklam SDK'larının Topics API ve Attribution Reporting'a geçmesi gerekecektir. Alarm ve hatırlatıcıları olan uygulamalar için — izin iletişim kutusu için UX uyarlaması. Bu değişiklikleri görmezden gelmek, Android 15'te çalışma zamanında uygulama çökmelerine veya bozuk reklam para kazanmaya yol açacaktır.

targetSdk ve compileSdk arasındaki fark

targetSdkVersion ve compileSdkVersion arasındaki fark, Android geliştiricileri arasında en yaygın kafa karışıklığı kaynaklarından biridir. compileSdkVersion, kodun derlendiği SDK sürümüdür. Derleme zamanında hangi API'lerin kullanılabilir olduğunu belirler ancak çalışma zamanı davranışını etkilemez. targetSdkVersion, uygulamanın test edildiği sürümdür — çalışma zamanında hangi behavioural changes'ların uygulanacağını belirler. compileSdk, targetSdk'den büyük veya eşit olabilir ve olmalıdır.

Kural basittir: compileSdk >= targetSdk >= minSdk. compileSdk genellikle en son kararlı API Level'a eşittir (2026'da — 36). targetSdk, test ettiğiniz sürümler arasında mümkün olduğunca yüksek olmalıdır. minSdk, maksimum erişim için mümkün olduğunca düşük olmalıdır. compileSdk'yi yükseltmek, behavioural changes'ları test etmeyi gerektirmez — yalnızca derleyici için yeni API'lere erişim açar. targetSdk'yi yükseltmek, tüm behavioural changes'ların tam test döngüsünü gerektirir.

Pratikte: Android 16'dan (API 36) yeni bir API kullanmak istiyor ancak API 36'nın behavioural changes'larını henüz test etmediyseniz, compileSdk = 36, targetSdk = 35 olarak ayarlayın. Kod yeni API'lerle derlenir ancak API 36'nın behavioural changes'ları uygulanmaz. Tüm değişiklikleri test ettikten sonra — targetSdk'yi 36'ya yükseltin.