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 olmayan bir arayüze referans verdiğinde veya yansıtma veya JNI kullanarak arayüzün adını almaya çalıştığında geçerli olur. Bu kısıtlamalar, kullanıcı ve geliştirici deneyimini iyileştirmeye, kullanıcılar için kilitlenme risklerini ve geliştiriciler için acil kullanıma sunma risklerini azaltmaya yardımcı olmak amacıyla uygulanmıştır. Bu karar hakkında 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 farklar

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

Uygulamalar, kilitlenmelerin ve beklenmedik davranışların önüne geçmek için SDK'daki sınıfların yalnızca resmi olarak belgelenmiş bölümlerini kullanmalıdır. Bu, yansıma gibi mekanizmaları kullanarak bir sınıfla etkileşime geçtiğinizde 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üyle birlikte SDK olmayan ek arayüzler kısıtlanır. Bu kısıtlamaların yayınlama iş akışınızı etkileyebileceğinin farkındayız. Bu nedenle, SDK dışı arayüzlerin kullanımını algılamanıza, bize geri bildirim verme fırsatına ve yeni politikaları planlayıp bunlara uyum sağlamaya zaman ayırmanıza yardımcı olacak araçlara sahip olduğunuzdan emin olmak istiyoruz.

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

Uygulamanızın hedef API düzeyine bağlı olarak SDK dışı bazı arayüzleri kullanabilirsiniz. Ancak SDK dışı bir yöntem veya alan kullanmak her zaman uygulamanızın bozulma riskini artırır. Uygulamanız SDK dışı arayüzlere dayanı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 kullanmanın alternatifini 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 (Geliştirici Önizlemesi)

Android 16 için SDK dışı tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: a22d5c2fa9c24ec0b864f0680208e9794222d1921114abe3245979143ce6d1c6

Android 16'daki SDK dışı API listesindeki değişiklikler hakkında daha fazla bilgi edinmek için Android 16'daki SDK dışı 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 ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

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

Android 14

Android 14 (API düzeyi 34) için SDK dışı tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

Android 14'teki SDK dışı API listesindeki değişiklikler hakkında daha fazla bilgi edinmek için Android 14'teki SDK dışı arayüz kısıtlamalarında yapılan güncellemeler başlıklı makaleyi inceleyin.

Android 13

Android 13 (API düzeyi 33) için SDK dışındaki tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 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 dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için Android 13'teki SDK dışı arayüz kısıtlamalarında yapılan güncellemeler başlıklı makaleyi inceleyin.

Android 12

Android 12 (API düzeyi 31) için SDK dışı tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 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 listesindeki değişiklikler 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 SDK olmayan tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 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 listesindeki değişiklikler hakkında daha fazla bilgi edinmek için Android 11'deki liste değişiklikleri başlıklı makaleyi inceleyin.

Android 10

Android 10 (API düzeyi 29) için SDK dışındaki tüm arayüzleri ve ilgili listelerini açıklayan aşağıdaki dosyayı indirebilirsiniz:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 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 dışı API listesindeki değişiklikler 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 listede yer alan) 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 türetilir.

AOSP'den liste oluşturma

AOSP ile çalışırken SDK dışı tüm arayüzleri ve bunların listelerini içeren bir hiddenapi-flags.csv dosyası oluşturabilirsiniz. Bunu yapmak için AOSP kaynağını indirin ve ardından aşağıdaki komutu çalıştırın:

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

Ardından dosyayı aşağıdaki 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 SDK dışı bir arayüze erişmeye çalışırsa karşılaşabileceğiniz davranış açıklanmaktadır.

Uygulamanızı SDK dışı arayüzler açısından test etme

Uygulamanızda SDK dışı arayüz olup olmadığını test etmek için kullanabileceğiniz birkaç yöntem vardır.

Hata ayıklaması yapılabilecek 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ıklama yapılabilir bir uygulama oluşturup çalıştırarak SDK dışı arayüzleri test edebilirsiniz. Kullandığınız cihazın veya emülatörünün, uygulamanızın hedef API düzeyiyle eşleştiğinden emin olun.

Uygulamanızda testler yürütülürken uygulamanız belirli SDK dışı arayüzlere erişirse sistem bir günlük mesajı yazdırır. Aşağıdaki ayrıntıları bulmak için uygulamanızın günlük mesajlarını inceleyebilirsiniz:

• Tanımlayan 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ıma kullanma veya JNI kullanma.
• SDK olmayan 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 simgesini kullanabilirsiniz. Örneğin, günlükteki bir giriş şu şekilde görünebilir:

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

StrictMode API'yi kullanarak test etme

StrictMode API'sini kullanarak SDK dışı arayüzleri de test edebilirsiniz. Bunu etkinleştirmek için detectNonSdkApiUsage yöntemini kullanın. StrictMode API'yi etkinleştirdikten sonra, SDK olmayan bir arayüzün her kullanımı için bir geri çağırma alabilirsiniz. Bu geri çağırma için penaltyListener kullanarak özel işlem uygulayabilirsiniz. Geri çağırma işlevinde sağlanan Violation nesnesi Throwable'ten türetilir ve ekteki yığın izleme, kullanımın bağlamını sağlar.

Veridex aracını kullanarak test etme

APK'nızda veridex statik analiz aracını da çalıştırabilirsiniz. Veridex aracı, üçüncü taraf kitaplıklar dahil APK'nın kod tabanının tamamını tarar ve bulduğu SDK dışı arayüz kullanımlarını raporlar.

Veridex aracının sınırlamaları şunlardır:

• JNI aracılığıyla çağrıları algılayamaz.
• Yansıtma yoluyla yalnızca çağrıların bir alt kümesini algılayabilir.
• Etkin olmayan kod yolları için yaptığı analiz, API düzeyindeki kontrollerle sınırlıdır.
• Yalnızca SSE4.2 ve POPCNT talimatlarını destekleyen makinelerde çalıştırılabilir.

Windows

Yerel Windows ikili dosyaları sağlanmaz ancak Linux için Windows alt sistemini (WSL) kullanarak Linux ikili dosyalarını çalıştırarak veridex aracını Windows'ta çalıştırabilirsiniz. Bu bölümdeki adımları uygulamadan önce WSL'yi yükleyin ve Linux dağıtımınız olarak Ubuntu'yu seçin.

Ubuntu yüklendikten sonra bir Ubuntu terminali başlatın ve aşağıdaki adımları uygulayın:

1. Android çalışma zamanı önceden derlenmiş kodları deposundan veridex aracını indirin.
2. appcompat.tar.gz dosyasının içeriğini ayıkla.
3. Ayıklanan klasörde veridex-linux.zip dosyasını bulun ve ayıklayın.

4. Sıkıştırılmış klasöre gidin ve ardından aşağıdaki komutu çalıştırın. your-app.apk, test etmek istediğiniz APK'dır:

   ./appcompat.sh --dex-file=your-app.apk
   

macOS

Veridex aracını macOS'te çalıştırmak için aşağıdaki adımları uygulayın:

1. Android çalışma zamanı önceden derlenmiş kodları deposundan veridex aracını indirin.
2. appcompat.tar.gz dosyasının içeriğini ayıkla.
3. Ayıklanan klasörde veridex-mac.zip dosyasını bulun ve ayıklayın.

4. Sıkıştırılmış klasöre gidin ve ardından aşağıdaki komutu çalıştırın. Bu komutta /path-from-root/your-app.apk, sisteminizin kök dizininden başlayarak test etmek istediğiniz APK'nın yoludur:

   ./appcompat.sh --dex-file=/path-from-root/your-app.apk
   

Linux

Veridex aracını Linux'da çalıştırmak için aşağıdaki adımları uygulayın:

1. Android çalışma zamanı önceden derlenmiş kodları deposundan veridex aracını indirin.
2. appcompat.tar.gz dosyasının içeriğini ayıkla.
3. Ayıklanan klasörde veridex-linux.zip dosyasını bulun ve ayıklayın.

4. Sıkıştırılmış klasöre gidin ve ardından aşağıdaki komutu çalıştırın. your-app.apk, test etmek istediğiniz APK'dır:

   ./appcompat.sh --dex-file=your-app.apk
   

Android Studio lint aracını kullanarak test etme

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

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

Play Console'u kullanarak test etme

Uygulamanızı Play Console'daki bir test kanalına yüklediğinizde uygulamanız olası sorunlar açısından otomatik olarak test edilir ve bir lansman öncesi raporu oluşturulur. Uygulamanız SDK dışı arayüzler kullanıyorsa bu arayüzlerin hangi listeye ait olduğuna bağlı olarak lansman öncesi raporunda bir hata veya uyarı gösterilir.

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

Yeni bir herkese açık API isteme

Uygulamanızdaki bir özellik için SDK olmayan bir arayüz kullanmanın alternatifini 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ı da dahil olmak üzere, kullandığınız desteklenmeyen API.
• Bu API'leri neden kullanmanız gerektiği (yalnızca düşük düzey ayrıntılar değil, API'nin gerekli olduğu üst düzey özellikle ilgili ayrıntılar da dahil).
• İlgili herkese açık SDK API'lerinin amaçlarınız için neden yetersiz olduğunu açıklayın.
• 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 kullanıma sunulma olasılığını artırırsınız.

Diğer sorular

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

Genel sorular

Google, sorun izleyici 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, uygulamaların statik analizi yoluyla oluşturduk ve bu analizleri aşağıdaki yöntemlerle destekledik:

• Play'deki ve Play dışındaki en popüler uygulamaların manuel olarak test edilmesi
• Dahili raporlar
• Şirket içi 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ün listelerini değerlendirirken API kullanımını ve sorun izleyici üzerinden geliştirici geri bildirimlerini 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 bağlı olarak değişiklik gösterir. Bu komutlar için root erişimli bir cihaz gerekmez.

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

Erişimi etkinleştirmek için aşağıdaki adb'yi kullanın

komut:

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 dışı arayüzlerin tüm algılamasını devre dışı bırakır. Bu ayar, SDK dışı arayüz kullanımıyla ilgili tüm günlük mesajlarını devre dışı bırakır ve uygulamanızı StrictMode API'sini kullanarak test etmenizi engeller. Bu ayar önerilmez.
• 1: SDK dışı tüm arayüzlere erişimi etkinleştirin ancak SDK dışı arayüz kullanımıyla ilgili uyarılar içeren günlük mesajları yazdırın. Bu ayarı kullanmak, uygulamanızı StrictMode API'sini kullanarak test etmenize de olanak tanır.
• 2: Engellenenler listesine ait veya hedef API düzeyiniz için koşullu olarak engellenen SDK dışı arayüzlerin kullanımına izin vermeyin.

SDK olmayan arayüz listeleriyle ilgili sorular

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

Bunlar, platform dex dosyalarındaki alan ve yöntem erişim işareti bitlerinde kodlanır. 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ı?

OEM'ler kendi arayüzlerini engellenenler listesine (kara liste) ekleyebilir ancak AOSP SDK dışı API listelerinden kaldıramazlar. CDD bu tür değişiklikleri önler ve CTS testleri, Android Runtime'ın listeyi uyguladığından emin olur.

İlgili uygulamaların uyumluluğu hakkında sorular

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

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

dex2oat veya DEX dosyası üzerinde oynama yapmayı kısıtlamayı planlıyor musunuz?

dex2oat ikilisine erişimi kısıtlamaya yönelik aktif planlarımız yok ancak DEX dosya biçiminin, Dalvik yürütülebilir biçiminde herkese açık olarak belirtilen bölümlerin ötesinde herkese açık bir arayüz olmasını amaçlamıyoruz. dex2oat'ı ve DEX biçiminin belirtilmeyen bölümlerini herhangi bir zamanda değiştirme veya kaldırma hakkını saklı tutarız. Ayrıca, dex2oat tarafından üretilen türetilmiş dosyaların (ör. ODEX (OAT olarak da bilinir), VDEX ve CDEX) tümü belirsiz biçimlerdir.

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

SDK'ya göre uyumluluk şartlarından feragat etmeyi planlamıyoruz. Bir SDK geliştiricisi, uyumluluğu yalnızca desteklenmeyen (eski adıyla gri) listelerdeki arayüzlere bağlı olarak sağlayabiliyorsa SDK arayüzlerine veya diğer alternatiflere geçiş planlamaya başlamalı ve SDK dışı bir arayüz kullanmaya alternatif bulamadığı her durumda yeni bir herkese açık API istemelidir.

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

Evet, ancak platform anahtarıyla imzalanan uygulamaları ve bazı sistem resmi uygulamalarını muaf tutuyoruz. Bu muafiyetlerin yalnızca sistem görüntüsünün (veya güncellenmiş sistem görüntüsü uygulamalarının) parçası olan uygulamalar için geçerli olduğunu unutmayın. Liste yalnızca SDK API'leri yerine özel platform API'lerine göre oluşturulan uygulamalar içindir (LOCAL_PRIVATE_PLATFORM_APIS := true).