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ş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 dışı arayüzler arasındaki farkları açıklama

Genel olarak, herkese açık SDK arayüzleri, Android çerçevesi Paket Dizini. 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.

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 dışı API listeleri

Android'in her sürümünde SDK dışı diğer arayüzler kısıtlanmıştı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 olmayan 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
  • Desteği sonlandırıldı: blacklist
Uygulamanızın hedef API düzeyinden bağımsız olarak kullanamadığınız SDK dışı arayüzler. 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, bir uygulama ilgili API düzeyini hedeflediğinde kısıtlanan SDK dışı arayüzler bulunur.

Bu listeler, bir uygulamanın artık listedeki SDK dışı arayüzlere erişemeden önce hedefleyebileceği maksimum API düzeyine (max-target-x) göre etiketlenir. Ö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
Uygulamanızın kullanabileceği, kısıtlamasız SDK dışı 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
Uyumluluk Test Paketi (CTS) üzerinden testi kolaylaştıran API'ler gibi dahili sistem testi için kullanılan arayüzler. 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ş. 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. Bkz. aşağıdaki bölümleri inceleyebilirsiniz.

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ğlaması: 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 olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

Dosya: hiddenapi-flags.csv

SHA-256 sağlama: 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'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 olmayan tüm arayüzler ve bunlara karşılık gelen listeler:

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 ş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ış (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) listesi), derleme zamanında türetilir.

AOSP'den liste oluşturma

AOSP ile çalışırken SDK olmayan tüm arayüzleri ve bunların listelerini içeren bir hiddenapi-flags.csv dosyası oluşturabilirsiniz. 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 alana atıfta bulunan 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 iade edildi, 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ılabilecek 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 olabilir. 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 ç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.

Ç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'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 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ç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 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'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 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 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 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ı 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ı ve sorun izleyici üzerinden geliştirici geri bildirimlerini dikkate alırız.

SDK olmayan 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, API düzeyine bağlı olarak değişiklik gösterir. Bu komutlar için köklü 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ğıdakilerden birine ayarlayabilirsiniz değerleri:

  • 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: 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 listeleriyle ilgili 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 önler ve CTS testleri, Android Runtime'ın listeyi uyguladığından emin olur.

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

Android SDK'sı Java arayüzleri içerir. Platform, ilgili içerikleri 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?

SDK'ya göre uyumluluk şartlarından feragat etmeyi planlamıyoruz. Eğer Bir SDK geliştiricisinin uyumluluğu yalnızca Google Play'deki arayüzlere bağlı olarak desteklenmeyen (eski adıyla gri) listelerin kaldırıldığında, 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ı). Liste yalnızca SDK API'leri yerine özel platform API'lerine göre oluşturulan uygulamalar içindir (LOCAL_PRIVATE_PLATFORM_APIS := true).