SDK olmayan arayüzlerle ilgili kısıtlamalar

Android 9'dan (API düzeyi 28) itibaren platform, uygulamanızın kullanabileceği SDK dışı arayüzleri kısıtlar. Bu kısıtlamalar, bir uygulama SDK dışı bir arayüze başvurduğunda veya yansıma ya da JNI kullanarak bu arayüzün tanıtıcısını almaya çalıştığında geçerli olur. Bu kısıtlamalar, kullanıcı ve geliştirici deneyimini iyileştirmek, kullanıcılar için kilitlenme risklerini ve geliştiriciler için acil durum dağıtımlarını azaltmak amacıyla uygulanmıştır. Bu kararla ilgili daha fazla bilgi için SDK Olmayan Arayüzlerin Kullanımını Azaltarak Kararlılığı Artırma başlıklı makaleyi inceleyin.

SDK ve SDK olmayan arayüzler arasındaki farkı anlama

Genel olarak, herkese açık SDK arayüzleri, Android çerçevesi Paket Dizini'nde belgelenen arayüzlerdir. SDK olmayan arayüzlerin işlenmesi, API'nin soyutladığı bir uygulama ayrıntısıdır. Bu nedenle, bu arayüzler önceden haber verilmeksizin değiştirilebilir.

Uygulamaların kilitlenmesini ve beklenmedik davranışlar sergilemesini önlemek için uygulamalar, SDK'daki sınıfların yalnızca resmi olarak belgelenmiş kısımlarını kullanmalıdır. Bu aynı zamanda, yansıma gibi mekanizmaları kullanarak bir sınıfla etkileşimde bulunurken SDK'da listelenmeyen yöntemlere veya alanlara erişmemeniz gerektiği anlamına da gelir.

SDK dışı API listeleri

Android'in her sürümünde, SDK olmayan ek arayüzler kısıtlanır. Bu kısıtlamaların yayınlama iş akışınızı etkileyebileceğini biliyoruz. Bu nedenle, SDK dışı arayüzlerin kullanımını tespit edecek araçlara sahip olmanızı, bize geri bildirimde bulunma fırsatını yakalamanızı ve yeni politikaları planlayıp bunlara uyum sağlamak için zaman kazanmanızı istiyoruz.

SDK olmayan kısıtlamaların geliştirme iş akışınız üzerindeki etkisini en aza indirmek için SDK olmayan arayüzler, hedeflenen API düzeyine bağlı olarak kullanımlarının ne kadar sıkı kısıtlandığını tanımlayan listelere ayrılır. Aşağıdaki tabloda bu listelerin her biri açıklanmaktadır:

Liste Kod etiketleri Açıklama
Engellenenler listesi
  • blocked
  • Desteği sonlandırıldı: blacklist
 Uygulamanızın hedef API düzeyinden bağımsız olarak kullanamayacağınız SDK dışı arayüzler. Uygulamanız bu arayüzlerden birine erişmeye çalışırsa sistem hata verir.
Koşullu olarak engellendi
  • max-target-x
  • Desteği sonlandırıldı: greylist-max-x

Android 9'dan (API düzeyi 28) itibaren her API düzeyinde, bir uygulama o API düzeyini hedeflediğinde kısıtlanan SDK dışı arayüzler bulunur.

Bu listeler, bir uygulamanın listedeki SDK dışı arayüzlere erişemeden önce hedefleyebileceği maksimum API düzeyiyle (max-target-x) etiketlenir. Örneğin, Android Pie'da engellenmeyen ancak Android 10'da engellenen SDK dışı bir arayüz, max-target-p (greylist-max-p) listesinin bir parçasıdır. Burada "p", Pie veya Android 9'u (API düzeyi 28) ifade eder.

Uygulamanız, hedef API düzeyiniz için kısıtlanmış bir arayüze erişmeye çalışırsa sistem, API engellenenler listesindeymiş gibi davranır.
Desteklenmiyor
  • unsupported
  • Desteği sonlandırıldı: greylist
 Kısıtlanmamış ve uygulamanızın kullanabileceği SDK dışı arayüzler. Ancak bu arayüzlerin desteklenmediğini ve önceden haber verilmeksizin değiştirilebileceğini unutmayın. Bu arayüzlerin gelecekteki Android sürümlerinde max-target-x listesinde koşullu olarak engellenmesi beklenir.
SDK
  • Hem public-api hem de sdk
  • Desteği sonlandırıldı: Hem public-api hem de whitelist
 Serbestçe kullanılabilen ve artık resmi olarak belgelenmiş Android çerçevesi Paket Dizini'nin bir parçası olarak desteklenen arayüzler.
Test API'leri
  • test-api
 Compatibility Test Suite (CTS) aracılığıyla test yapmayı kolaylaştıran API'ler gibi dahili sistem testleri için kullanılan arayüzler. Test API'leri SDK'nın bir parçası değildir. Android 11'den (API düzeyi 30) itibaren test API'leri engellenenler listesine dahil edildiğinden, uygulamaların hedef API düzeyinden bağımsız olarak bu API'leri kullanmasına izin verilmez. Tüm test API'leri desteklenmez ve platform API düzeyinden bağımsız olarak önceden haber verilmeksizin değiştirilebilir.

Uygulamanızın hedef API düzeyine bağlı olarak bazı SDK dışı arayüzleri kullanabilirsiniz. Ancak SDK dışı yöntem veya alan kullanmak her zaman uygulamanızın bozulmasıyla ilgili yüksek risk taşır. Uygulamanız SDK dışı arayüzleri kullanıyorsa SDK arayüzlerine veya diğer alternatiflere geçiş planlamaya başlamanız gerekir. Uygulamanızdaki bir özellik için SDK dışı arayüz kullanmaya alternatif bulamıyorsanız yeni bir herkese açık API isteğinde bulunmanız gerekir.

Bir arayüzün hangi listeye ait olduğunu belirleme

SDK olmayan arayüzlerin listeleri, platformun bir parçası olarak oluşturulur. Her Android sürümü hakkında bilgi edinmek için aşağıdaki bölümlere bakın.

Android 16

Android 16 (API düzeyi 36) için, SDK dışı tüm arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

Android 16'daki SDK olmayan API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 16'daki SDK olmayan arayüz kısıtlamalarında yapılan güncellemeler başlıklı makaleyi inceleyin.

Android 15

Android 15 (API düzeyi 35) için, SDK dışı tüm arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

Android 15'teki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 15'teki SDK dışı arayüz kısıtlamalarıyla ilgili güncellemeler başlıklı makaleyi inceleyin.

Android 14

Android 14 (API düzeyi 34) için tüm SDK dışı arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

Android 14'teki SDK olmayan API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 14'teki SDK olmayan arayüz kısıtlamalarıyla ilgili güncellemeler başlıklı makaleyi inceleyin.

Android 13

Android 13 (API düzeyi 33) için, tüm SDK dışı arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

Android 13'te koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri de dahil olmak üzere Android 13'teki SDK olmayan API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 13'te SDK olmayan arayüz kısıtlamalarıyla ilgili güncellemeler başlıklı makaleyi inceleyin.

Android 12

Android 12 (API düzeyi 31) için, tüm SDK dışı arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

Android 12'de koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri de dahil olmak üzere Android 12'deki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 12 için liste değişiklikleri başlıklı makaleyi inceleyin.

Android 11

Android 11 (API düzeyi 30) için, tüm SDK dışı arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

Android 11'de koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri de dahil olmak üzere Android 11'deki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 11 için liste değişiklikleri başlıklı makaleyi inceleyin.

Android 10

Android 10 (API düzeyi 29) için, SDK dışı tüm arayüzleri ve bunlara karşılık gelen listeleri açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 denetim toplamı: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

Android 10'da koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri de dahil olmak üzere Android 10'daki SDK olmayan API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 10 için liste değişiklikleri başlıklı makaleyi inceleyin.

Android 9

Android 9 (API düzeyi 28) için aşağıdaki metin dosyası, kısıtlanmamış (gri listeye alınmış) SDK dışı API'lerin listesini içerir: hiddenapi-light-greylist.txt.

Engellenenler listesi (blacklist) ve koşullu olarak engellenen API'lerin listesi (koyu gri liste), derleme sırasında oluşturulur.

AOSP'den liste oluşturma

AOSP ile çalışırken tüm SDK dışı arayüzleri ve bunlara karşılık gelen listeleri içeren bir hiddenapi-flags.csv dosyası oluşturabilirsiniz. Bunun için AOSP kaynağını indirin ve aşağıdaki komutu çalıştırın:

m out/soong/hiddenapi/hiddenapi-flags.csv

Ardından dosyayı şu konumda bulabilirsiniz:

out/soong/hiddenapi/hiddenapi-flags.csv

Kısıtlanmış SDK dışı arayüzlere erişildiğinde beklenen davranış

Aşağıdaki tabloda, uygulamanız engellenenler listesinde yer alan bir SDK dışı arayüze erişmeye çalıştığında karşılaşabileceğiniz davranışlar açıklanmaktadır.

Erişim yöntemi Sonuç
Bir alana referans veren Dalvik talimatı NoSuchFieldError atıldı
Bir yönteme referans veren Dalvik talimatı NoSuchMethodError atıldı
Class.getDeclaredField() veya Class.getField() kullanarak yansıtma NoSuchFieldException atıldı
Class.getDeclaredMethod(), Class.getMethod() kullanılarak yansıtma NoSuchMethodException atıldı
Class.getDeclaredFields(), Class.getFields() kullanılarak yansıtma SDK üyesi olmayanlar sonuçlarda yer almaz
Class.getDeclaredMethods(), Class.getMethods() kullanılarak yansıtma SDK üyesi olmayanlar sonuçlarda yer almaz
env->GetFieldID() kullanan JNI NULL iade edildi, NoSuchFieldError atıldı
env->GetMethodID() kullanan JNI NULL iade edildi, NoSuchMethodError atıldı

Uygulamanızı SDK olmayan arayüzler için test etme

Uygulamanızda SDK olmayan arayüzleri test etmek için kullanabileceğiniz birkaç yöntem vardır.

Hata ayıklanabilir bir uygulama kullanarak test etme

Android 9 (API düzeyi 28) veya sonraki sürümlerin yüklü olduğu bir cihazda ya da emülatörde hata ayıklanabilir bir uygulama derleyip çalıştırarak SDK dışı arayüzleri test edebilirsiniz. Kullandığınız cihazın veya emülatörün, uygulamanızın hedef API düzeyiyle eşleştiğinden emin olun.

Sistem, uygulamanızda testler çalıştırırken uygulamanız belirli SDK dışı arayüzlere erişirse bir günlük mesajı yazdırır. Uygulamanızın günlük mesajlarını inceleyerek aşağıdaki ayrıntıları bulabilirsiniz:

  • Bildirimde bulunan sınıf, ad ve tür (Android çalışma zamanı tarafından kullanılan biçimde).
  • Erişim yöntemi: Bağlantı oluşturma, yansıtma kullanma veya JNI kullanma.
  • SDK dışı arayüzün ait olduğu liste.

Çalışan uygulamanın PID'si altında görünen bu günlük mesajlarına erişmek için adb logcat aracını kullanabilirsiniz. Örneğin, günlükteki bir giriş aşağıdaki gibi görünebilir:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

StrictMode API'yi kullanarak test etme

SDK olmayan arayüzleri test etmek için StrictMode API'sini de kullanabilirsiniz. Bunu etkinleştirmek için detectNonSdkApiUsage yöntemini kullanın. StrictMode API'sini etkinleştirdikten sonra, SDK dışı bir arayüzün her kullanımı için penaltyListener kullanarak geri çağırma alabilir ve özel işleme uygulayabilirsiniz. Geri çağırmada sağlanan Violation nesnesi Throwable sınıfından türetilir ve ekteki yığın izleme (stack trace), kullanım bağlamını sağlar.

Android Studio lint aracını kullanarak test etme

Uygulamanızı Android Studio'da her derlediğinizde hata analizi aracı, kodunuzu olası sorunlar açısından inceler. Uygulamanız SDK olmayan arayüzler kullanıyorsa bu arayüzlerin ait olduğu listeye bağlı olarak derleme hataları veya uyarılar görebilirsiniz.

Ayrıca, lint aracını komut satırından çalıştırabilir veya belirli bir proje, klasör ya da dosya üzerinde denetimleri manuel olarak çalıştırabilirsiniz.

Google Play Console'u kullanarak test etme

Uygulamanızı Play Console'da bir test kanalına yüklediğinizde uygulamanız olası sorunlar için otomatik olarak test edilir ve bir lansman öncesi rapor oluşturulur. Uygulamanız SDK dışı arayüzler kullanıyorsa lansman öncesi raporda, bu arayüzlerin ait olduğu listeye bağlı olarak bir hata veya uyarı gösterilir.

Daha fazla bilgi için Sorunları tanımlamak için lansman öncesi raporları kullanma başlıklı makaledeki Android Uyumluluğu bölümüne bakın.

Yeni bir herkese açık API isteğinde bulunma

Uygulamanızdaki bir özellik için SDK dışı arayüz kullanmaya alternatif bulamıyorsanız sorun izleyicimizde özellik isteği oluşturarak yeni bir herkese açık API isteğinde bulunabilirsiniz.

Özellik isteği oluştururken aşağıdaki bilgileri sağlayın:

  • Accessing hidden ... logcat mesajında görülen tam tanımlayıcı dahil olmak üzere, kullandığınız desteklenmeyen API.
  • API'nin gerekli olduğu üst düzey özellik hakkındaki ayrıntılar da dahil olmak üzere bu API'leri neden kullanmanız gerektiği (yalnızca alt düzey ayrıntılar değil).
  • İlgili herkese açık SDK API'lerinin neden amaçlarınız için yetersiz olduğu.
  • Denediğiniz diğer alternatifler ve bunların neden işe yaramadığı

Özellik isteğinizde bu ayrıntıları sağladığınızda yeni bir herkese açık API'nin onaylanma olasılığını artırırsınız.

Diğer sorular

Bu bölümde, geliştiricilerin sıkça sorduğu diğer soruların yanıtları yer almaktadır:

Genel sorular

Google, Issue Tracker aracılığıyla tüm uygulamaların ihtiyaçlarını karşılayabileceğinden nasıl emin olabilir?

Android 9 (API düzeyi 28) için ilk listeleri, aşağıdaki yöntemler kullanılarak desteklenen uygulamaların statik analiziyle oluşturduk:

  • Google Play'deki ve Google Play dışındaki en popüler uygulamaların manuel olarak test edilmesi
  • dahili raporlar
  • Dahili kullanıcılardan otomatik veri toplama
  • geliştirici önizleme raporları
  • daha fazla yanlış pozitif içerecek şekilde tasarlanmış ek statik analiz

Her yeni sürüm için listeleri değerlendirirken API kullanımının yanı sıra sorun izleyici aracılığıyla geliştirici geri bildirimlerini de dikkate alırız.

SDK olmayan arayüzlere erişimi nasıl etkinleştirebilirim?

API yaptırım politikasını değiştirmek için adb komutlarını kullanarak geliştirme cihazlarında SDK dışı arayüzlere erişimi etkinleştirebilirsiniz. Kullandığınız komutlar API düzeyine göre değişir. Bu komutlar için root erişimli cihaz gerekmez.

Android 10 (API düzeyi 29) veya sonraki sürümler

Erişimi etkinleştirmek için aşağıdaki adb komutunu kullanın:

komutunu kullanın:

adb shell settings put global hidden_api_policy  1

API yaptırım politikasını varsayılan ayarlara sıfırlamak için aşağıdaki komutu kullanın:

adb shell settings delete global hidden_api_policy
Android 9 (API düzeyi 28)

Erişimi etkinleştirmek için aşağıdaki adb komutlarını kullanın:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

API yaptırım politikasını varsayılan ayarlara sıfırlamak için aşağıdaki komutları kullanın:

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

API yaptırım politikasındaki tam sayıyı aşağıdaki değerlerden birine ayarlayabilirsiniz:

  • 0: SDK olmayan arayüzlerin algılanmasını tamamen devre dışı bırakır. Bu ayarın kullanılması, SDK olmayan arayüz kullanımıyla ilgili tüm günlük mesajlarını devre dışı bırakır ve StrictMode API'yi kullanarak uygulamanızı test etmenizi engeller. Bu ayar önerilmez.
  • 1: SDK olmayan tüm arayüzlere erişimi etkinleştirir ancak SDK olmayan arayüz kullanımları için uyarı içeren günlük mesajları yazdırır. Bu ayarı kullanarak uygulamanızı StrictMode API ile test edebilirsiniz.
  • 2: Engellenenler listesinde yer alan veya hedef API düzeyiniz için koşullu olarak engellenen SDK dışı arayüzlerin kullanımına izin verilmez.

SDK olmayan arayüz listeleriyle ilgili sorular

Sistem görüntüsünde SDK dışı API listelerini nerede bulabilirim?

Platform dex dosyalarındaki alan ve yöntem erişim işareti bitlerinde kodlanırlar. Sistem görüntüsünde bu listeleri içeren ayrı bir dosya yoktur.

SDK dışı API listeleri, aynı Android sürümlerine sahip farklı OEM cihazlarda aynı mıdır?

OEM'ler kendi arayüzlerini engellenenler listesine (kara liste) ekleyebilir ancak AOSP SDK dışı API listelerinden arayüzleri kaldıramazlar. CDD bu tür değişiklikleri önler ve CTS testleri, Android Çalışma Zamanı'nın listeyi uygulamasını sağlar.

Yerel kodda NDK dışı arayüzlerle ilgili herhangi bir kısıtlama var mı?

Android SDK'sı, Java arayüzleri içerir. Platform, Android 7'de (API düzeyi 26) yerel C/C++ kodu için NDK olmayan arayüzlere erişimi kısıtlamaya başladı. Daha fazla bilgi için Android N'de Özel C/C++ Sembol Kısıtlamalarıyla Kararlılığı Artırma başlıklı makaleyi inceleyin.

dex2oat veya DEX dosyası manipülasyonunu kısıtlama planı var mı?

dex2oat ikili programına erişimi kısıtlamaya yönelik etkin planlarımız yok ancak DEX dosya biçiminin, Dalvik Yürütülebilir biçiminde herkese açık olarak belirtilen kısımlar dışında kararlı veya herkese açık bir arayüz olmasını amaçlamıyoruz. dex2oat'ı ve DEX biçiminin belirtilmemiş kısımlarını herhangi bir zamanda değiştirme veya kaldırma hakkını saklı tutarız. Ayrıca, dex2oat tarafından üretilen ODEX (OAT olarak da bilinir), VDEX ve CDEX gibi türetilmiş dosyaların tümü belirtilmemiş biçimlerdir.

Önemli bir üçüncü taraf SDK'sı (ör. kod karartıcı), SDK dışı arayüzleri kullanmaktan kaçınamıyor ancak gelecekteki Android sürümleriyle uyumluluğu sürdürmeyi taahhüt ediyorsa ne olur? Android bu durumda uyumluluk şartlarından feragat edebilir mi?

Uyumluluk şartlarından SDK bazında feragat etme planımız yoktur. Bir SDK geliştiricisi, uyumluluğu yalnızca desteklenmeyen (eski adıyla gri) listelerdeki arayüzlere bağlı kalarak sağlayabiliyorsa SDK arayüzlerine veya diğer alternatiflere geçiş planlamaya başlamalı ve SDK dışı bir arayüz kullanmaya alternatif bulamadığında yeni bir herkese açık API isteğinde bulunmalıdır.

SDK dışı arayüz kısıtlamaları yalnızca üçüncü taraf uygulamaları için değil, sistem ve birinci taraf uygulamaları da dahil olmak üzere tüm uygulamalar için geçerli mi?

Evet ancak platform anahtarıyla imzalanmış uygulamalar ve bazı sistem görüntüsü uygulamaları bu kapsamda değildir. Bu muafiyetlerin yalnızca sistem görüntüsünün parçası olan uygulamalar (veya güncellenmiş sistem görüntüsü uygulamaları) için geçerli olduğunu unutmayın. Bu liste yalnızca SDK API'leri yerine özel platform API'leri (LOCAL_PRIVATE_PLATFORM_APIS := true) için geliştirilen uygulamalara yöneliktir.