SDK olmayan arayüzlerle ilgili kısıtlamalar

Android 9'dan (API düzeyi 28) itibaren platform, SDK olmayan arayüzleri vardır. Bu kısıtlamalar, bir uygulama ya da yansıma veya JNI kullanarak herkese açık kullanıcı adını edinmeye çalışıyor. Bu kısıtlamalar, kullanıcı ve geliştiricinin iyileştirilmesine yardımcı olmak için uygulanmıştır ve kullanıcılar için kilitlenme ve acil durum kullanımına yönelik riskleri azaltmak üzere birlikte çalışır. Bu kararla ilgili daha fazla bilgi edinmek için Kararlılığı Artırma başlıklı makaleyi inceleyin. SDK dışı arayüzlerin kullanımını azaltarak

SDK ve SDK dışı arayüzler arasındaki farkları açıklama

Genel olarak, herkese açık SDK arayüzleri, Android çerçevesi Paket Dizini. SDK olmayan arayüzlerin kullanımı soyutladığı için bu arayüzler de otomatik olarak haber verilmeksizin değiştirilebilir.

Kilitlenmeleri ve beklenmeyen davranışları önlemek için uygulamalar, resmi olarak yalnızca SDK'daki sınıfların belgelenmiş bölümlerini gözden geçirin. Bu aynı zamanda sunumlarınızın bir kullanıcı veya sağlayıcıyla etkileşimde bulunduğunuzda SDK'da listelenmeyen düşünme egzersizlerini kullanan bir sınıf oluşturur.

SDK olmayan API listeleri

Android'in her sürümünde SDK dışı diğer arayüzler kısıtlanmıştır. Biz bu kısıtlamaların yayın iş akışınızı etkileyebileceğini biliyor ve SDK dışı arayüzlerin kullanımını tespit edecek araçlara sahip olduğunuzdan emin olun. Bu, bize geri bildirim gönderin ve yeni politikalara uyum sağlamak için zaman kazanın.

SDK dışı kısıtlamaların geliştirme iş akışınız üzerindeki etkisini en aza indirmek için SDK dışı arayüzler, kullanımlarının ne kadar sıkı olduğunu tanımlayan listelere ayrılır. hedeflenmekte olan API düzeyine bağlı olarak kısıtlanır. Aşağıdaki tablo şu listelerin her birini açıklar:

Liste Kod etiketleri Açıklama
Engellenenler listesi
  • blocked
  • Kullanımdan kaldırıldı: blacklist
 Uygulamanız ne olursa olsun kullanamayacağınız SDK dışı arayüzler hedef API düzeyi. Uygulamanız bu arayüzlerden birine erişmeye çalışırsa sistem bir hata verir.
Koşula bağlı olarak engellendi
  • max-target-x
  • Kullanımdan kaldırıldı: greylist-max-x

Android 9'dan (API düzeyi 28) itibaren her API düzeyinde SDK olmayan özellikler Uygulama söz konusu API düzeyini hedeflediğinde kısıtlanan arayüzler.

Bu listeler maksimum API düzeyi ile etiketlenir (max-target-x) daha uzun süre erişemeyebilirsiniz. Örneğin, Android Pie'de engellenmemiş ancak şu anda engellenmiş olan SDK olmayan arayüz - Android 10, max-target-p kapsamındadır (greylist-max-p) listesi, burada "p" Pie veya Android anlamına gelir 9 (API düzeyi 28).

Uygulamanız, yalnızca düzeyinde bir kontrol gerçekleştirirseniz, sistem bu API, Google Analytics 4'ün bir parçası engellenenler listesine ekleyin.
Desteklenmiyor
  • unsupported
  • Kullanımdan kaldırıldı: greylist
 Kısıtlanmamış ve uygulamanızın kullanabileceği SDK olmayan arayüzler. Not Ancak bu arayüzlerin desteklenmediğini ve haber verilmeksizin değiştirilebilir. Bu arayüzler şu anda gelecekteki Android sürümlerinde koşullu olarak engellenecektir max-target-x listesi.
SDK
  • Hem public-api hem de sdk
  • Desteği sonlandırıldı: public-api ve whitelist
 özgürce kullanılabilen ve artık resmi olarak belgelenmiş Android çerçevesi Paket Dizini.
API'leri test et
  • test-api
 Dahili sistem testi için kullanılan arayüzler. Örneğin, Uyumluluk Test Paketi (CTS) aracılığıyla testi kolaylaştırır. Test API'leri SDK'nın bir parçası değildir. Şunun içinde başlıyor: Android 11 (API düzeyi 30), test API'leri engellenenler listesine dahildir. uygulamaların, hedef API düzeyleri ne olursa olsun bunları kullanmasına izin verilmez. Tümü test API'leri desteklenmez ve tercih edebilirsiniz.

Uygulamanızın hedef API'sine bağlı olarak bazı SDK dışı arayüzleri kullanabilirsiniz düzeyinde) olduğu gibi, SDK olmayan herhangi bir yöntem veya alanın kullanılması her zaman en iyi şekilde yararlanabilirsiniz. Uygulamanız SDK dışı arayüz kullanıyorsa SDK arayüzlerine veya diğer alternatiflere geçiş. Bir SDK dışı bir arayüz kullanmaya alternatif olarak, yeni bir herkese açık API isteğinde bulunun.

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

SDK olmayan arayüzlerin listeleri, platformun bir parçası olarak oluşturulur. Bkz. aşağıdaki bölümleri inceleyebilirsiniz.

Android 15

Android 15 (API düzeyi 35) için SDK olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9.

Android 15'teki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için: Android 15'te SDK dışı arayüz kısıtlamalarında yapılan güncellemeler adlı makaleyi inceleyin.

Android 14

Android 14 (API düzeyi 34) için SDK olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f.

Android 14'teki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için: Android 14'te SDK dışı arayüz kısıtlamalarında yapılan güncellemeler adlı makaleyi inceleyin.

Android 13

Android 13 (API düzeyi 33) için, şunların açıklandığı aşağıdaki dosyayı indirebilirsiniz: SDK olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3.

Android 13'teki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için: koşullu olarak ayarlanan API'ler için önerilen herkese açık API alternatifleri dahil Android 13'te engellenmiş. SDK dışı arayüzde yapılan güncellemelere bakın kısıtlamalar hakkında bilgi edinin.

Android 12

Android 12 (API düzeyi 31) için SDK olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761.

Android 12'deki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi edinmek için: koşullu olarak ayarlanan API'ler için önerilen herkese açık API alternatifleri dahil daha fazla bilgi için Şunlar için değişiklikleri listeleme bölümüne bakın: Android 12.

Android 11

Android 11 (API düzeyi 30) için şu dosyayı indirebilirsiniz: aşağıda açıklandığı gibi, SDK dışı tüm arayüzler ve bunlara karşılık gelen listeler açıklanmıştır:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56.

Android 11'deki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi: koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri Android 11 için Android 11 için değişiklikleri listeleme bölümüne bakın.

Android 10

Android 10 (API düzeyi 29) için şu dosyayı indirebilirsiniz: aşağıda açıklandığı gibi, SDK dışı tüm arayüzler ve bunlara karşılık gelen listeler açıklanmıştır:

Dosya: hiddenapi-flags.csv

SHA-256 sağlaması: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb.

Android 10'daki SDK dışı API listesi değişiklikleri hakkında daha fazla bilgi: koşullu olarak engellenen API'ler için önerilen herkese açık API alternatifleri Android 10 için Android 10 için değişiklikleri listeleme bölümüne bakın.

Android 9

Android 9 (API düzeyi 28) için aşağıdaki metin dosyası, Kısıtlanmamış SDK olmayan API'ler (gri listede): hiddenapi-light-greylist.txt.

Engellenenler listesi (blacklist) ve koşullu olarak engellenen API'lerin listesi (koyu gri) listesi), derleme zamanında türetilir.

AOSP'den liste oluşturma

AOSP ile çalışırken, yeni bir sürüm tanımlamak için hiddenapi-flags.csv SDK dışı tüm arayüzleri ve bunlara karşılık gelen listelerini içerir. Bunun 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 durumunda gerçekleşebilecek davranışlar Engellenenler listesinde olan SDK olmayan bir arayüze erişmeye çalışıyor.

Erişim araçları Sonuç
Bir alanı referans gösteren Dalvik talimatı NoSuchFieldError atıldı
Bir yöntemi referans alan Dalvik talimatı NoSuchMethodError atıldı
Class.getDeclaredField() veya Class.getField() kullanarak düşünme NoSuchFieldException atıldı
Class.getDeclaredMethod(), Class.getMethod() kullanarak düşünme NoSuchMethodException atıldı
Class.getDeclaredFields(), Class.getFields() kullanarak düşünme SDK olmayan üyeler sonuçlarda yer almıyor
Class.getDeclaredMethods(), Class.getMethods() kullanarak düşünme SDK olmayan üyeler sonuçlarda yer almıyor
env->GetFieldID() kullanılarak JNI NULL geri döndü, NoSuchFieldError atıldı
env->GetMethodID() kullanılarak JNI NULL geri döndü, NoSuchMethodError atıldı

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

SDK olmayan arayüzleri test etmek için kullanabileceğiniz çeşitli yöntemler vardır: en iyi şekilde yararlanabilirsiniz.

Hata ayıklaması yapılabilir bir uygulama kullanarak test etme

SDK olmayan arayüzleri test etmek için kendi oluşturduğunuz Android 9 (API düzeyi 28) çalıştıran bir cihazda veya emülatörde hata ayıklanabilir uygulama ya da daha yüksek. Kullandığınız cihazın veya emülatörün Uygulamanızın hedef API düzeyini.

Uygulamanızda testler çalıştırırken uygulamanızın SDK dışı belirli arayüzlere erişmesi. Uygulamanızın günlük mesajlarını inceleyebilirsiniz. şu ayrıntıları bulabilirsiniz:

  • Tanımlayan sınıf, ad ve tür ( Android çalışma zamanı).
  • Erişim araçları: bağlama, yansıma kullanarak veya JNI kullanma.
  • SDK dışı arayüzün ait olduğu liste.

adb logcat Çalışan uygulamanın PID'si. Örneğin, günlükteki bir giriş aşağıdaki gibi olabilir:

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

StrictMode API'sini kullanarak test etme

Ayrıca, StrictMode API'yi kullanarak SDK dışı arayüzleri test edebilirsiniz. Şunu kullanın: detectNonSdkApiUsage yöntemini kullanabilirsiniz. StrictMode API, SDK dışı her kullanım için geri çağırma alabilirsiniz arayüz oluşturmak için penaltyListener kullanarak ele alacağız. Geri çağırmada sağlanan Violation nesnesi, Throwable ve ekteki yığın izleme (stack trace), kullanım bağlamını sağlar.

Sürüm aracını kullanarak test etme

APK'nızda verdex statik analiz aracını da çalıştırabilirsiniz. Veridex aracı Üçüncü taraf kitaplıklar da dahil olmak üzere APK'nın tüm kod tabanını tarar ve bulduğu SDK dışı arayüzlerin tüm kullanımlarını bildirir.

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

  • Uygulama, JNI üzerinden yapılan çağrıları algılayamaz.
  • Yansıma yoluyla yalnızca bir çağrı alt kümesini algılayabilir.
  • Etkin olmayan kod yollarıyla ilgili analizi 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 programları sağlanmamıştır ancak veridex aracını şurada çalıştırabilirsiniz: Linux için Windows Alt Sistemi'ni kullanarak Linux ikili programlarını yürüterek Windows (WSL) tuşlarına basın. Bu bölümdeki adımları uygulamadan önce WSL'yi yükleyin ve Linux dağıtımınız olarak Ubuntu'yu seçmeniz gerekir.

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

  1. Önceden oluşturulmuş Android çalışma zamanı sürümlerinden veridex aracını indirin. depodur.
  2. appcompat.tar.gz dosyasının içeriğini çıkarın.
  3. Çıkarılan klasörde veridex-linux.zip dosyasını bulup çıkarın.

  4. Sıkıştırılmamış klasöre gidin ve 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. Önceden oluşturulmuş Android çalışma zamanı sürümlerinden veridex aracını indirin. depodur.
  2. appcompat.tar.gz dosyasının içeriğini çıkarın.
  3. Çıkarılan klasörde veridex-mac.zip dosyasını bulup çıkarın.

  4. Sıkıştırılmamış klasöre gidin ve aşağıdaki komutu çalıştırın; /path-from-root/your-app.apk, APK'nın yoludur sisteminizin kök dizininden başlayarak test etmek istediğiniz yeni bir komut dosyası oluşturun:

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

Linux

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

  1. Önceden oluşturulmuş Android çalışma zamanı sürümlerinden veridex aracını indirin. depodur.
  2. appcompat.tar.gz dosyasının içeriğini çıkarın.
  3. Çıkarılan klasörde veridex-linux.zip dosyasını bulup çıkarın.

  4. Sıkıştırılmamış klasöre gidin ve 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

Uygulamanızı Android Studio'da her derlediğinizde, lint aracı sorunları çözebilmelisiniz. Uygulamanız SDK olmayan arayüzler kullanıyorsa arayüzlerin hangi listeye ait olduğuna bağlı olarak, hatalar veya uyarılar .

Ayrıca, lint aracını komut satırından çalıştırabilir veya incelemeler çalıştırabilirsiniz. manuel olarak düzenleyebilirsiniz.

Play Console'u kullanarak test etme

Uygulamanızı Play Console'da bir test kanalına yüklediğinizde, uygulamanız Potansiyel sorunlar açısından otomatik olarak test edilir ve elde edilir. Uygulamanız SDK olmayan arayüzler kullanıyorsa o arayüzlerin hangi listeye ait olduğuna bağlı olarak lansman öncesi rapora dahil edilir.

Daha fazla bilgi için Lansman öncesi uygulamayı kullanma konusundaki Android Uyumluluğu bölümüne bakın. raporlarından yararlanabilirsiniz.

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

Bir özellik için SDK dışı arayüz kullanmanın alternatifini uygulamanızda özellik isteği oluşturarak yeni bir herkese açık API isteğinde bulunabilirsiniz sorun izleyicimize göz atın.

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

  • Şurada görülen tam tanımlayıcı da dahil olmak üzere, desteklenmeyen API'yi kullandığınız Accessing hidden ... logcat mesajı var.
  • Üst düzey kullanıcılarla ilgili ayrıntılar da dahil olmak üzere, bu API'leri neden kullanmanız gerekiyor? gereken bir diğer unsur da bu.
  • İlgili herkese açık SDK API'lerinin amaçlarınız için neden yeterli olmadığı
  • Denediğiniz diğer alternatifler ve işe yaramama nedenleri.

Bu ayrıntıları özellik isteğinizde sağladığınızda, yeni bir genel API verilme olasılığını gösterir.

Diğer sorular

Bu bölümde, geliştiricilerin sorduğu diğer soruların sık sorulan sorular:

Genel sorular

Google, sorun izleyici aracılığıyla tüm uygulamaların ihtiyaçlarını yakalayabileceğinden nasıl emin olabilir?

Android 9 (API düzeyi 28) için ilk listeleri, aşağıdaki yöntemlerle desteklenen uygulamaların analizi:

  • Play'deki ve Play dışındaki en popüler uygulamalar için manuel test
  • dahili raporlar
  • dahili kullanıcılardan otomatik veri toplama
  • geliştirici önizleme raporları
  • daha ihtiyatlı bir şekilde daha fazla veriyi kapsamak üzere tasarlanmış yanlış pozitifler

Her yeni sürümün listelerini değerlendirirken API kullanımını, sorun izleyici aracılığıyla geliştirici geri bildirimi alın.

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

Adb kullanarak geliştirme cihazlarında SDK dışı arayüzlere erişimi etkinleştirebilirsiniz API'nin zorunlu kılma politikasını değiştirmek için komut dosyası kullanıyorsanız. Kullandığınız komutlar değişkenlik gösterebilir. veya API düzeyine göre değişir. Bu komutlar rootlanmış bir cihaz gerektirmez.

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'yi zorunlu kılma politikasını varsayılan ayarlara sıfırlamak için şunu kullanın: şu 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'yi zorunlu kılma politikasını varsayılan ayarlara sıfırlamak için şunu kullanın: şu 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ğıdakilerden birine ayarlayabilirsiniz değerleri:

  • 0: SDK olmayan arayüzlerin tüm algılamasını devre dışı bırakın. Bu ayarın kullanılması şunları devre dışı bırakır: SDK dışı arayüz kullanımıyla ilgili tüm günlük mesajlarını gösterir ve StrictMode API'yi kullanan bir uygulamadır. Bu ayar önerilmez.
  • 1: Tüm SDK dışı arayüzlere erişimi etkinleştirin, ancak günlük mesajlarını SDK dışı arayüz kullanımlarıyla ilgili uyarılar. Bu ayarı kullandığınızda şunları yapabilirsiniz: StrictMode API'yi kullanarak uygulamanızı test edin.
  • 2: Engellenenler listesine ait olan veya hedef API düzeyiniz için koşullu olarak engellenmiş olmalıdır.

SDK olmayan arayüz listeleri hakkında sorular

Sistem görüntüsünde SDK olmayan 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 bunu yapamazlar AOSP SDK dışı API listelerindeki arayüzleri kaldırma CDD bu tür değişiklikleri engeller CTS testleri Android Çalışma Zamanının listeyi zorunlu kılmasını sağlar.

Yerel kodda NDK olmayan arayüzler için herhangi bir kısıtlama var mı?

Android SDK'sı Java arayüzleri içerir. Platformda kısıtlamalar Android 7'de (API düzeyi 26) yerel C/C++ kodu için NDK olmayan arayüzlere erişim. Daha fazla bilgi için Özel C/C++ Sembolüyle Kararlılığı Artırma Android N'deki kısıtlamalar.

Dex2oat veya DEX dosyası işlemeyi kısıtlamaya yönelik bir plan var mı?

Dex2oat ikili programına erişimi kısıtlamak için etkin bir planımız yok ancak DEX dosya biçiminin kararlı veya Dalvik Yürütülebilir biçiminde herkese açık olarak belirtilen bölümler. Dex2oat ve belirtilmemiş kısımları değiştirme veya kaldırma hakkını saklı tutarız. değiştirebilirsiniz. Ayrıca, dex2oat tarafından üretilen türetilmiş dosyaların ODEX (OAT olarak da bilinir), VDEX ve CDEX belirtilmemiş biçimlerdir.

Önemli bir üçüncü taraf SDK (örneğin, kod karartma aracı) SDK dışı arayüzleri kullanmaktan kaçınsa da gelecekteki Android sürümleriyle uyumluluğu korumayı taahhüt ederse ne olur? Bu durumda Android, uyumluluk gereksinimlerinden feragat edebilir mi?

Her SDK için uyumluluk şartlarından feragat etme planımız bulunmamaktadır. Eğer Bir SDK geliştiricisinin uyumluluğu yalnızca Google Play'deki arayüzlere bağlı olarak desteklenmeyen (eski adıyla gri) listelerin geri kalanına SDK arayüzlerini veya diğer alternatifleri kullanın ve her seferinde yeni bir herkese açık API isteğinde bulunun SDK dışı bir arayüz kullanmanın alternatifi bulamazlar.

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 midir?

Evet, ancak platform anahtarı ve bazı sistem görüntüleri ile imzalanan uygulamalar muaf tutulur Bu muafiyetlerin yalnızca sisteme dahil olan uygulamalar için geçerli olduğunu unutmayın. görüntüsü (veya güncellenmiş sistem görüntüsü uygulamaları). Bu liste yalnızca şu uygulamalarda kullanılabilir: yerine özel platform API'lerinde derleyerek (ör. LOCAL_PRIVATE_PLATFORM_APIS := true) bilgileri gösterilir.