SDK Uzantıları

SDK uzantıları, daha önce yayınlanmış belirli API düzeyleri için API'leri herkese açık SDK'ya eklemek üzere modüler sistem bileşenlerinden yararlanır. Bu API'ler, son kullanıcılar Google Play sistem güncellemeleri aracılığıyla modül güncellemeleri aldığında cihazlara gönderilir. Uygulama geliştiriciler, Android'in önceki sürümlerinde SDK'da bulunmayan ek işlevler sağlamak için uygulamalarında bu API'leri kullanabilir.

API Sürümü Oluşturma

Android 11'den (API düzeyi 30) itibaren Android cihazlar bir dizi SDK uzantısı içerir. Yeni API'ler eklendiğinde bir API düzeyine dahil edilir ancak belirli bir sürümün SDK uzantısına da dahil edilebilir. Örneğin, Fotoğraf Seçici için ACTION_PICK_IMAGES API'si Android 13'te (API düzeyi 33) herkese açık SDK'ya eklendi ancak R Uzantıları Sürüm 2'den itibaren SDK uzantıları aracılığıyla da kullanılabilir. SDK uzantı adları, bir tam sayı sabitine karşılık gelir. Bu sabit, Build.VERSION_CODES içindeki bir sabit veya SdkExtensions sınıfında tanımlanan bir sabittir (ör. SdkExtensions.AD_SERVICES).

Hangi SDK uzantılarının kullanılacağını belirleme

SDK uzantı API'lerini kullanabilmek için öncelikle uygulamanızın kullanım alanlarını destekleyen API'leri içeren SDK'ları belirlemeniz gerekir.

SDK Uzantısı API'leri için API referans sayfaları, uygulamanızın bir API'ye erişmek için kullanabileceği en eski SDK uzantısı sürümünü belirtir. Dokümanda bir Android platform sürümü de belirtilmişse (API düzeyine göre referans verilir) bu API, Android'in ilgili sürümünü veya sonraki sürümlerini çalıştıran tüm cihazlarda da kullanılabilir.

Örneğin, ACTION_PICK_IMAGES genel olarak Android 13'ten (API düzeyi 33) itibaren herkese açık SDK'da kullanılabilir ancak cihazda en az R Extensions 2 sürümü bulunduğu sürece Android 11'e (API düzeyi 30) kadarki cihazlarda da kullanılabilir:

Bu API'yi kullanmak için en az API düzeyi 33 veya en az 2 uzantı düzeyine sahip bir SDK'ya göre derlemeniz gerekir.

Uzatma SDK'sını kullanmak için aşağıdaki adımları uygulayın:

1. Kullanmak istediğiniz API'lerin özellik dokümanlarını ve API referansını kontrol ederek ihtiyacınız olan minimum uzantı sürümünü bulun.
2. Özellik kümeniz için gerekli uzantı sürümünü belirledikten sonra Android Studio'da SDK Yöneticisi'ni açın.
3. İlgili uzantı sürümünü (veya API'ler eklemeli olduğundan daha yüksek bir sürümü) içeren Android SDK Platform girişini seçin. Örneğin: Android SDK Platform 33, Uzatma Seviyesi 4.

4. Uygulamanızın build.gradle.kts veya build.gradle dosyasında aşağıdaki değerleri beyan edin:

   Groovy

   android {
       compileSdk 33
       compileSdkExtension 4
       ...
   }
   

   Kotlin

   android {
       compileSdk = 33
       compileSdkExtension = 4
       ...
   }
   

SDK uzantılarının kullanılıp kullanılamayacağını kontrol etme

Uygulamanız, çalışma zamanında hangi SDK uzantı sürümlerinin kullanılabileceğini kontrol edebilir. Geliştirme sırasında, aşağıdaki bölümlerde açıklandığı gibi Android Debug Bridge (adb) komutlarını kullanarak uzantı sürümlerini arayabilirsiniz.

Çalışma zamanında kontrol etme

Uygulamanız, getExtensionVersion() yöntemini kullanarak SDK uzantılarının belirli bir platform sürümünde kullanılıp kullanılamayacağını çalışma zamanında kontrol edebilir. Örneğin, aşağıdaki kod Android 11 (API düzeyi 30) SDK uzantısı için 2 veya daha yeni bir uzantı sürümünün kullanılıp kullanılamayacağını kontrol eder:

fun isPhotoPickerAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2
    // Safely use extension APIs that are available with Android 11 (API level 30) Extensions Version 2, such as Photo Picker.
}

public static final boolean isPhotoPickerAvailable() {
    return SdkExtensions.getExtensionVersion(Build.VERSION_CODES.R) >= 2;
}

Bu, Build.VERSION.SDK_INT değerine göre kontrol yapmaya benzer:

fun isPhotoPickerAvailable(): Boolean {
    return Build.VERSION.SDK_INT >= 33
}

public static final boolean isPhotoPickerAvailable() {
    return Build.VERSION.SDK_INT >= 33;
}

Bu SDK_INT kontrolü hâlâ güvenli ve geçerlidir ancak uzantı API'si kullanılabilir olsa bile isPhotoPickerAvailable bazı cihazlarda yanlış değerini döndürür. Sonuç olarak, SDK_INT kontrolü optimal değildir ve API kullanılabilirliğini kontrol etmenin daha iyi bir yolu uzantı sürümü kontrolüdür. 33 veya 33'ten büyük SDK_INT değerine sahip tüm cihazlar (Android 13 veya sonraki sürümler), herkese açık SDK'da Fotoğraf Seçici API'lerine sahiptir. Ancak SDK_INT değeri 33'ten düşük olan cihazlar (ör. Android 11, 12 ve 12L) da en az 2 sürümüne sahip R uzantısı sürümlerine sahipse API'lere erişebilir.

Bu durumda, uzantı sürümü kontrolü kullanmak uygulamanızın daha fazla kullanıcıya ek işlevler sunmasına yardımcı olabilir. Bir cihazda belirli SDK uzantılarını kontrol etmek için kullanabileceğiniz tüm sabitlerin listesi için SDK uzantısı adları ve sabitleri bölümüne bakın.

Reklam Hizmetleri Uzantıları

Genel SDK uzantıları grubuna benzer şekilde, AdServices API referansı bazen bir API'nin "Reklam Hizmetleri Uzantıları" sürümünün bir parçası olduğunu gösterir. Genel SDK uzantılarının aksine, reklam hizmetleri uzantıları bir cihazda hangi sürümün kullanıldığını belirlemek için SdkExtensions.AD_SERVICES sabit değerini kullanır:

fun isAdServicesAvailable(): Boolean {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4
}

public static final boolean isAdServicesAvailable() {
    return SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4;
}

Ad Services uzantılarındaki özellikler ve bu uzantıları kullanmaya başlama hakkında daha fazla bilgi edinmek için Ad Services uzantıları dokümanlarını inceleyin.

Yardımcı program yöntemleri

Bazı durumlarda SDK uzantılarında, SDK uzantı API'lerinin kullanılabilirliğini kontrol etmek için Jetpack yardımcı program yöntemleri bulunur. Örneğin, PhotoPicker'ın kullanılabilirliğini kontrol etmek için bir Jetpack kitaplık işlevi kullanabilirsiniz. Bu işlev, koşullu sürüm kontrollerini soyutlar.

Araçlar desteği

Android Studio Flamingo | 2022.2.1 veya sonraki sürümlerde lint aracı, NewAPI kontrolü kapsamında SDK uzantısı sürümleriyle ilgili sorunları tarayabilir. Ayrıca Android Studio, SDK uzantıları kullanılarak başlatılan API'ler için doğru sürüm kontrollerini otomatik olarak oluşturabilir.

SDK uzantısı adları ve sabitler

Aşağıdaki tabloda, API referans dokümanlarında listelenen farklı SDK uzantısı gruplarının, uygulamanızın çalışma zamanında API kullanılabilirliğini kontrol etmek için kullanabileceği sabitlerle nasıl eşlendiği açıklanmaktadır. Her herkese açık SDK için genel SDK uzantıları grubu, Build.VERSION_CODES değerleriyle eşlenir.

adb kullanarak kontrol etme

adb kullanarak bir cihazda hangi SDK uzantılarının kullanılabildiğini kontrol etmek için aşağıdaki komutu çalıştırın:

adb shell getprop | grep build.version.extensions

Komutu çalıştırdıktan sonra aşağıdakine benzer bir çıkış görürsünüz:

[build.version.extensions.r]: [3] # Android 11 (API level 30) and higher
[build.version.extensions.s]: [3] # Android 12 (API level 31) and higher
[build.version.extensions.t]: [3] # Android 13 (API level 33) and higher

Her satırda, cihazda bulunan bir SDK uzantısı ve ilgili uzantı sürümü (bu durumda 3) gösterilir.