Pembatasan pada antarmuka non-SDK

Android 9 (API level 28) memperkenalkan pembatasan baru pada penggunaan antarmuka non-SDK, baik secara langsung, lewat pencerminan, atau lewat JNI. Pembatasan ini diterapkan bila aplikasi mereferensikan antarmuka non-SDK atau berusaha memperoleh penanganannya menggunakan pencerminan atau JNI. Untuk informasi selengkapnya tentang keputusan ini, lihat Meningkatkan Stabilitas dengan Mengurangi Penggunaan Antarmuka non-SDK.
Secara umum, aplikasi seharusnya hanya menggunakan bagian-bagian class yang telah didokumentasikan secara resmi di SDK. Khususnya, ini berarti bahwa Anda seharusnya tidak berencana mengakses metode atau kolom yang tidak tercantum dalam SDK bila berinteraksi dengan class melalui semantik seperti pencerminan.
Penggunaan metode atau kolom demikian sangat berisiko merusak aplikasi Anda.

 

Membedakan antara antarmuka SDK dan non-SDK

Biasanya, antarmuka SDK adalah SDK yang telah didokumentasikan dalam Package Index framework Android. Penanganan antarmuka non-SDK adalah detail implementasi yang diabstraksikan API; hal ini sewaktu-waktu dapat berubah tanpa pemberitahuan.
Android 9 memperkenalkan pembatasan baru pada penggunaan antarmuka non-SDK, baik secara langsung, lewat pencerminan, atau lewat JNI. Pembatasan ini diterapkan bila aplikasi mereferensikan antarmuka non-SDK atau berusaha memperoleh penanganannya menggunakan pencerminan atau JNI.

 

Pengujian untuk antarmuka non-SDK

Anda bisa menguji aplikasi dengan mendownload Android 9. Sistem akan mencetak log dan mungkin saja menampilkan toast jika aplikasi Anda mengakses antarmuka non-SDK yang termasuk dalam "daftar abu-abu". Jika aplikasi Anda memanggil antarmuka non-SDK yang masuk dalam "daftar hitam", sistem akan melontarkan error.
Perhatikan toast, yang menarik perhatian ke antarmuka yang diusulkan untuk dikenakan pembatasan. Selain itu, pastikan memeriksa pesan log aplikasi Anda, yang berisi informasi lebih detail tentang antarmuka non-SDK yang diakses aplikasi Anda, termasuk class yang mendeklarasikan, nama dan tipe dalam format yang digunakan oleh waktu proses Android. Pesan log juga menunjukkan cara akses: langsung, lewat pencerminan, atau lewat JNI. Terakhir, pesan log menampilkan apakah antarmuka non-SDK yang dipanggil ada dalam daftar abu-abu atau daftar hitam.
Anda bisa menggunakan adb logcat untuk mengakses pesan log ini, yang muncul pada PID aplikasi yang berjalan. Misalnya, entri dalam log mungkin akan terbaca seperti berikut:

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

Antarmuka non-SDK yang ada dalam daftar abu-abu mencakup beberapa metode dan kolom yang tetap berfungsi di Android 9, tetapi kami tidak memberikan akses ke metode dan kolom itu di versi platform mendatang. Jika ada alasan yang membuat Anda tidak bisa mengimplementasikan strategi alternatif ke API dalam daftar abu-abu, Anda boleh melaporkan bug untuk meminta pertimbangan ulang atas pembatasan tersebut.
Beberapa API ada pada "daftar hitam", lebih ketat daripada metode yang masuk daftar abu-abu. Metode-metode yang ada dalam daftar hitam menyebabkan aplikasi melontarkan pengecualian seperti yang ditampilkan dalam tabel di Hasil mempertahankan antarmuka non-SDK.
Android 9 mendukung StrictMode untuk antarmuka non-SDK, yang disebut detectNonSdkApiUsage, jadi bila aplikasi Anda memanggil aplikasi dalam daftar abu-abu, pelacakan tumpukan akan menampilkan konteksnya.

 

Hasil mempertahankan antarmuka non-SDK

Tabel berikut menyediakan detail tentang cara akses dan hasilnya masing-masing.

Cara akses	Hasil
Instruksi Dalvik yang merujuk suatu kolom	NoSuchFieldError dilontarkan
Instruksi Dalvik yang merujuk suatu metode	NoSuchMethodError dilontarkan
Pencerminan lewat Class.getDeclaredField() atau Class.getField()	NoSuchFieldException dilontarkan
Pencerminan lewat Class.getDeclaredMethod(), Class.getMethod()	NoSuchMethodException dilontarkan
Pencerminan lewat Class.getDeclaredFields(), Class.getFields()	Anggota non-SDK tidak ada dalam hasil
Pencerminan lewat Class.getDeclaredMethods(), Class.getMethods()	Anggota non-SDK tidak ada dalam hasil
JNI lewat env->GetFieldID()	NULL ditampilkan, NoSuchFieldError dilontarkan
JNI lewat env->GetMethodID()	NULL ditampilkan, NoSuchMethodError dilontarkan

FAQ

 

Pertanyaan umum

Apa saja antarmuka non-SDK?

Antarmuka tersebut adalah kolom dan metode Java yang bukan bagian dari SDK Android resmi. Semua itu adalah detail implementasi yang sewaktu-waktu dapat berubah tanpa pemberitahuan.

Apa yang terjadi di Android 9?

Kami sedang menyiapkan pembatasan pada penggunaan antarmuka non-SDK. Bentuk pembatasan ini bervariasi (lihat Bagaimana mendeteksi penggunaan antarmuka non-SDK saat aplikasi saya berjalan?), tetapi bisa memengaruhi perilaku aplikasi Anda jika menggunakan antarmuka non-SDK.

Jika saya saat ini menggunakan antarmuka non-SDK, ke mana saya harus memintanya?

Laporkan Permintaan Fitur, dan berikan info detail tentang kasus penggunaan Anda.

Apa saja ragam daftar untuk membatasi antarmuka non-SDK, dan apa artinya dalam konteks perilaku restriktif?

Di bawah ini adalah tipe daftar tersebut:

• daftar putih: SDK
• daftar abu-abu muda: metode/kolom non-SDK yang tetap dapat diakses.
• daftar abu-abu tua:
  • Untuk aplikasi yang menargetkan SDK di bawah API level 28: setiap penggunaan antarmuka daftar abu-abu tua diizinkan.
  • Untuk aplikasi yang target SDK-nya adalah API level 28 atau yang lebih tinggi: sama perilakunya seperti daftar hitam
• daftar hitam: dibatasi, apa pun target SDK-nya. Platform akan berperilaku seakan tidak ada antarmuka. Misalnya, akan dilontarkan NoSuchMethodError/NoSuchFieldException bila aplikasi mencoba menggunakannya, dan tidak akan menyertakannya bila aplikasi ingin tahu daftar kolom/metode class tertentu.

Aplikasi saya menggunakan banyak library pihak ketiga, sehingga menyulitkan saya untuk menemukan API pribadi yang sedang digunakan. Adakah fitur waktu-kompilasi untuk membantu saya melacak pelanggaran?

Anda bisa mencoba fitur analisis statis veridex yang tersedia di AOSP.

Bagaimana cara mendeteksi penggunaan antarmuka non-SDK saat aplikasi saya berjalan?

Sebuah peringatan logcat akan dicetak dalam bentuk Accessing hidden field|method .... Sebagai tambahan, pesan toast akan ditampilkan untuk aplikasi yang bisa di-debug dan pesan logcat akan dicetak untuk antarmuka non-SDK yang ditolak.

Bagaimana cara Google memastikan bahwa mereka akan menangkap kebutuhan semua aplikasi melalui issuetracker?

Kami mula-mula menanamkan daftar melalui analisis statis aplikasi yang telah kami tambahkan padanya:

• pengujian manual aplikasi teratas Play dan non-Play
• laporan internal
• pengumpulan data otomatis dari pengguna internal
• laporan pratinjau developer
• analisis statis tambahan yang didesain untuk menyertakan lebih banyak false-positive secara konservatif

Bagaimana cara mengaktifkan akses ke API non-SDK?

Mengaktifkan akses ke API non-SDK bisa dilakukan pada perangkat pengembangan dengan menggunakan adb.
Jika Anda ingin melihat informasi akses API di keluaran logcat adb, Anda bisa mengubah kebijakan pemberlakuan API:

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

Untuk mengembalikannya ke setelan default:

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

Perintah-perintah ini tidak memerlukan perangkat yang telah di-root.
Arti integer yang diberikan adalah:

• 0: Menonaktifkan deteksi penggunaan API non-SDK. Ini juga akan menonaktifkan logging, serta memutus API mode ketat, detectNonSdkApiUsage(). Tidak disarankan.
• 1: "Peringatkan saja" - mengizinkan akses ke semua API non-SDK, tetapi mempertahankan peringatan dalam log. API mode ketat akan terus bekerja.
• 2: Melarang penggunaan API yang masuk dalam daftar abu-abu tua dan daftar hitam.
• 3: Melarang penggunaan API yang ada dalam daftar hitam, tetapi mengizinkan penggunaan API yang ada dalam daftar abu-abu tua.

 

Tentang daftar API

Apa isi daftar abu-abu tua dalam build rilis Android 9?

Daftar abu-abu tua berisi metode/kolom yang setahu kami belum pernah digunakan selama masa pengembangan kami, tetapi mungkin terlewatkan. Metode/kolom yang dipilih untuk dimasukkan dalam daftar abu-abu tua adalah yang berkaitan erat dengan antarmuka publik di SDK dan daftar abu-abu muda.

Di manakah lokasi daftar abu-abu/daftar hitam?

Semuanya telah di-build sebagai bagian dari platform. Anda bisa menemukan entri bawaan di sini:

• platform/prebuilts/runtime/appcompat/hiddenapi-light-greylist.txt: Daftar AOSP untuk API abu-abu muda
• platform/prebuilts/runtime/appcompat/hiddenapi-dark-greylist.txt: Daftar AOSP untuk API abu-abu tua

Selain itu, daftar ini berisi daftar API abu-abu muda SDK 28.
Daftar hitam dan daftar abu-abu tua diperoleh pada waktu build. Kami telah menambahkan aturan build yang menghasilkan daftar-daftar tersebut di AOSP. Ini tidak sama seperti daftar hitam di P, tetapi tumpang-tindih cukup bagus. Developer bisa download AOSP kemudian menghasilkan daftar hitam dengan perintah berikut:

  make hiddenapi-aosp-blacklist

Selanjutnya mereka akan menemukan file tersebut di:

  out/target/common/obj/PACKAGING/hiddenapi-aosp-blacklist.txt

Kira-kira berapakah ukuran daftar-daftar ini?

Daftar tersebut sekitar:

• daftar putih (juga dikenal sebagai SDK) ~= 74.000 metode dan kolom
• daftar abu-abu muda ~= 11.000 metode dan kolom
• daftar abu-abu tua ~= 121.000 metode dan kolom
• daftar hitam ~= 9.000 metode dan kolom

Di manakah saya bisa menemukan daftar hitam/daftar abu-abu dalam citra sistem?

Daftar itu dienkode dalam bit tanda akses kolom dan metode di file dex platform. Tidak ada file terpisah di citra sistem yang berisi daftar ini.

Apakah daftar hitam/daftar abu-abu sama pada perangkat OEM yang berbeda dengan versi Android yang sama?

Ya, OEM bisa menambahkan API mereka sendiri ke daftar hitam, tetapi tidak bisa menghapus apa pun dari daftar hitam atau daftar abu-abu asli/AOSP. CDD mencegah perubahan demikian dan pengujian CTS memastikan bahwa Waktu Proses Android memberlakukan daftar tersebut.

 

Pertanyaan kompatibilitas terkait aplikasi

Adakah pembatasan pada antarmuka non-NDK di kode bawaan?

SDK meliputi bahasa Java. Untuk NDK bagi kode bawaan C/C++, kami melakukannya di Android Nougat. Lihat: Meningkatkan Stabilitas dengan Pembatasan Simbol C/C++ Pribadi di Android N

Adakah rencana untuk membatasi manipulasi file dex2oat atau dex?

Kami tidak memiliki rencana aktif untuk membatasi akses ke biner dex2oat, tetapi kami tidak bermaksud bahwa format file dex akan stabil atau antarmuka publik melebihi porsi yang telah ditetapkan secara publik di format Dalvik Executable. Kami berhak memodifikasi atau menghilangkan bagian dex2oat dan bagian format dex yang tidak ditetapkan kapan saja. Juga perhatikan bahwa file hasil yang diproduksi melalui dex2oat seperti odex (juga dikenal sebagai oat), vdex, dan cdex, semuanya adalah format yang tidak ditetapkan.

Bagaimana jika SDK 3p yang krusial (khususnya, obfuscator) tidak bisa mencegah penggunaan antarmuka non-SDK, tetapi malah melakukan untuk mempertahankan kompatibilitas dengan versi Android mendatang? Bisakah Android menghilangkan peringatannya?

Kami tidak ada rencana untuk menghilangkan persyaratan kompatibilitas atas dasar SDK. Jika mitra SDK merasa bahwa mereka tidak dapat mempertahankan kompatibilitas dengan daftar putih + set API daftar abu-abu saat ini, mereka harus melaporkan bug yang meminta metode non- SDK yang akan mereka butuhkan.
Catatan: Untuk Android 9, kami tidak ada rencana membatasi antarmuka non-SDK yang saat ini digunakan oleh aplikasi Android atau SDK, tetapi di masa mendatang, kami berencana untuk mulai mengenakan pembatasan SDK target bila kami merasa ada alternatif SDK yang cocok. Perhatikan, banyak dari SDK ini yang rusak setiap tahunnya lantaran menggunakan antarmuka non-SDK dan non-NDK serta harus beradaptasi.

Apakah pembatasan antarmuka non-SDK berlaku pada semua aplikasi termasuk sistem dan aplikasi pihak pertama, bukan cuma aplikasi pihak ketiga?

Ya, akan tetapi, kami mengecualikan aplikasi yang ditandatangani dengan kunci platform, dan kami juga memiliki daftar putih package untuk beberapa aplikasi citra sistem. Perhatikan, pengecualian ini hanya berlaku pada aplikasi yang ada dalam citra sistem (atau aplikasi citra sistem yang telah diupdate). Daftar tersebut hanya dimaksudkan untuk aplikasi yang di-build untuk API platform pribadi, bukannya API SDK (yakni LOCAL_PRIVATE_PLATFORM_APIS := true).

Sebagian developer telah memposting mekanisme pembatasan API pribadi dan teknik melakukan bypass. Apa komentar Anda tentang hal ini? Apakah Anda akan membuat pembatasan menjadi lebih keras lagi? 

Kami menyadari ada beberapa solusi yang potensial. Untungnya sebagian besar aplikasi terpaku pada API publik. Walaupun kami mencoba membuatnya lebih keras untuk memanggil antarmuka non-SDK guna memastikan kompatibilitas, kami perlu menyeimbangkannya dengan membuat waktu proses tetap mudah di-debug. Kami akan terus mengevaluasi implementasi yang mendasarinya serta bekerja sama dengan para developer.

Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.


Source:

Pembatasan pada antarmuka non-SDK