Mulai Android 9 (Level API 28), platform ini membatasi antarmuka non-SDK yang dapat digunakan aplikasi Anda. Pembatasan ini berlaku saat aplikasi mereferensikan antarmuka non-SDK atau mencoba mendapatkan handle-nya menggunakan refleksi atau JNI. Pembatasan ini diberlakukan untuk membantu meningkatkan pengalaman pengguna dan developer, serta mengurangi risiko error bagi pengguna dan peluncuran darurat bagi developer. Untuk mengetahui informasi selengkapnya tentang keputusan ini, baca Meningkatkan Stabilitas dengan Mengurangi Penggunaan Antarmuka non-SDK.
Membedakan antarmuka SDK dan non-SDK
Secara umum, antarmuka SDK publik adalah antarmuka yang didokumentasikan dalam Indeks Paket framework Android. Penanganan antarmuka non-SDK adalah detail implementasi yang disederhanakan oleh API, sehingga antarmuka ini dapat berubah tanpa pemberitahuan.
Untuk menghindari error dan perilaku tidak terduga, aplikasi hanya dapat menggunakan bagian class yang didokumentasikan secara resmi di SDK. Itu artinya Anda tidak dapat mengakses metode atau kolom yang tidak tercantum dalam SDK ketika berinteraksi dengan class melalui mekanisme seperti refleksi.
Daftar API non-SDK
Untuk setiap rilis Android, antarmuka non-SDK tambahan dibatasi. Kami mengetahui bahwa pembatasan ini dapat memengaruhi alur kerja rilis Anda, dan kami ingin memastikan bahwa Anda memiliki alat untuk mendeteksi penggunaan antarmuka non-SDK, kesempatan untuk memberi kami masukan, serta waktu untuk merencanakan dan menyesuaikan dengan kebijakan yang baru.
Untuk meminimalkan dampak pembatasan non-SDK pada alur kerja pengembangan Anda, antarmuka non-SDK dibagi menjadi beberapa daftar yang menjelaskan seberapa ketat penggunaannya dibatasi, bergantung pada level API yang ditargetkan. Tabel berikut menjelaskan masing-masing dari daftar ini:
| Daftar | Tag kode | Deskripsi |
|---|---|---|
| Daftar yang Tidak Diizinkan |
|
Antarmuka non-SDK yang tidak dapat digunakan, apa pun API level target aplikasi Anda. Jika aplikasi Anda mencoba mengakses salah satu antarmuka ini, sistem akan menampilkan error. |
| Diblokir bersyarat |
|
Mulai Android 9 (API level 28), setiap API level memiliki antarmuka non-SDK yang dibatasi ketika aplikasi menargetkan API level tersebut. Daftar ini diberi label oleh level API maksimum
( Jika aplikasi Anda mencoba mengakses antarmuka yang dibatasi untuk API level target Anda, sistem akan berperilaku seolah-olah API merupakan bagian dari daftar yang tidak diizinkan. |
| Tidak Didukung |
|
Antarmuka non-SDK yang tidak dibatasi dan dapat digunakan aplikasi Anda. Namun,
perlu diperhatikan bahwa antarmuka ini tidak didukung dan
dapat berubah tanpa pemberitahuan. Antarmuka ini dapat
diblokir bersyarat di versi Android berikutnya dalam daftar
max-target-x. |
| SDK |
|
Antarmuka yang dapat digunakan secara bebas dan saat ini didukung sebagai bagian dari Indeks Paket framework Android yang didokumentasikan secara resmi. |
| API Pengujian |
|
Antarmuka yang digunakan untuk pengujian sistem internal, seperti API yang memfasilitasi pengujian melalui Compatibility Test Suite (CTS). API Pengujian bukan bagian dari SDK. Mulai Android 11 (level API 30), API pengujian disertakan dalam daftar yang tidak diizinkan, sehingga aplikasi tidak diizinkan untuk menggunakannya, apa pun level API targetnya. Semua API pengujian tidak didukung dan dapat berubah tanpa pemberitahuan, terlepas dari level API platform. |
Meskipun Anda dapat menggunakan sebagian antarmuka non-SDK (bergantung pada level API target aplikasi Anda), penggunaan metode atau kolom non-SDK apa pun tetap berisiko tinggi membuat aplikasi mengalami error. Jika aplikasi Anda bergantung pada antarmuka non-SDK, Anda harus mulai merencanakan migrasi ke antarmuka SDK atau alternatif lainnya. Jika tidak dapat menemukan alternatif penggunaan antarmuka non-SDK untuk fitur dalam aplikasi Anda, sebaiknya minta API publik baru.
Menentukan daftar untuk antarmuka
Daftar antarmuka non-SDK dibuat sebagai bagian dari platform ini. Lihat bagian berikut untuk mengetahui informasi tentang setiap rilis Android.
Android 15
Untuk Android 15 (level API 35), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 15, lihat Pembaruan pembatasan antarmuka non-SDK di Android 15.
Android 14
Untuk Android 14 (level API 34), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 14, lihat Pembaruan pembatasan antarmuka non-SDK di Android 14.
Android 13
Untuk Android 13 (API level 33), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 13, termasuk alternatif API publik yang disarankan untuk API yang diblokir bersyarat di Android 13, lihat Pembaruan pembatasan antarmuka non-SDK di Android 13.
Android 12
Untuk Android 12 (level API 31), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 12, termasuk alternatif API publik yang disarankan untuk API yang diblokir bersyarat di Android 12, lihat Perubahan daftar untuk Android 12.
Android 11
Untuk Android 11 (API level 30), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 11, termasuk alternatif API publik yang disarankan untuk API yang diblokir bersyarat di Android 11, lihat Perubahan daftar untuk Android 11.
Android 10
Untuk Android 10 (API level 29), Anda dapat mendownload file berikut yang menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya:
File: hiddenapi-flags.csv
Checksum SHA-256:
f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Untuk mempelajari lebih lanjut perubahan daftar API non-SDK di Android 10, termasuk alternatif API publik yang disarankan untuk API yang diblokir bersyarat di Android 10, lihat Perubahan daftar untuk Android 10.
Android 9
Untuk Android 9 (level API 28), file teks berikut berisi daftar
API non-SDK yang tidak dibatasi (masuk daftar abu-abu):
hiddenapi-light-greylist.txt
Daftar yang tidak diizinkan (blacklist) dan daftar API yang diblokir bersyarat (daftar
abu-abu gelap) diperoleh pada waktu build.
Membuat daftar dari AOSP
Saat menangani AOSP, Anda dapat membuat file hiddenapi-flags.csv yang
berisi semua antarmuka non-SDK dan daftar yang terkait dengan antarmuka tersebut. Untuk melakukannya,
download sumber AOSP, lalu jalankan perintah berikut:
m out/soong/hiddenapi/hiddenapi-flags.csv
Anda kemudian dapat menemukan file tersebut di lokasi berikut:
out/soong/hiddenapi/hiddenapi-flags.csv
Perilaku yang akan terjadi saat mengakses antarmuka non-SDK yang dibatasi
Tabel berikut menjelaskan perilaku yang akan terjadi jika aplikasi Anda mencoba mengakses antarmuka non-SDK yang merupakan bagian dari daftar yang tidak diizinkan.
| Cara akses | Hasil |
|---|---|
| Petunjuk Dalvik yang merujuk sebuah kolom | NoSuchFieldError ditampilkan |
| Petunjuk Dalvik yang merujuk sebuah metode | NoSuchMethodError ditampilkan |
Refleksi menggunakan Class.getDeclaredField() atau Class.getField() |
NoSuchFieldException ditampilkan |
Refleksi menggunakan Class.getDeclaredMethod(), Class.getMethod() |
NoSuchMethodException ditampilkan |
Refleksi menggunakan Class.getDeclaredFields(), Class.getFields() |
Anggota non-SDK tidak ada dalam hasil |
Refleksi menggunakan Class.getDeclaredMethods(), Class.getMethods() |
Anggota non-SDK tidak ada dalam hasil |
JNI menggunakan env->GetFieldID() |
NULL ditunjukkan, NoSuchFieldError ditampilkan |
JNI menggunakan env->GetMethodID() |
NULL ditunjukkan, NoSuchMethodError ditampilkan |
Menguji aplikasi untuk antarmuka non-SDK
Ada beberapa metode yang dapat digunakan untuk menguji antarmuka non-SDK di aplikasi Anda.
Pengujian menggunakan aplikasi yang dapat di-debug
Anda dapat melakukan pengujian untuk antarmuka non-SDK dengan membangun dan menjalankan aplikasi yang dapat di-debug di perangkat atau emulator yang menjalankan Android 9 (level API 28) atau yang lebih tinggi. Pastikan perangkat atau emulator yang Anda gunakan sesuai dengan level API target aplikasi Anda.
Saat menjalankan pengujian pada aplikasi Anda, sistem akan menampilkan pesan log jika aplikasi Anda mengakses antarmuka non-SDK tertentu. Anda dapat memeriksa pesan log aplikasi Anda untuk menemukan detail berikut:
- Class, nama, dan jenis yang mendeklarasikan (dalam format yang digunakan oleh Android runtime).
- Cara akses: menautkan, menggunakan refleksi, atau menggunakan JNI.
- Daftar yang mencakup antarmuka non-SDK.
Anda dapat menggunakan adb logcat untuk mengakses pesan log ini, yang muncul di bawah PID aplikasi yang sedang berjalan. Contohnya, entri dalam log mungkin terlihat seperti berikut:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Pengujian menggunakan StrictMode API
Anda juga dapat melakukan pengujian untuk antarmuka non-SDK menggunakan StrictMode API. Gunakan
metode detectNonSdkApiUsage untuk mengaktifkannya. Setelah mengaktifkan
StrictMode API, Anda dapat menerima callback untuk setiap penggunaan antarmuka non-SDK
menggunakan penaltyListener, yang dapat Anda gunakan untuk mengimplementasikan
penanganan kustom. Objek Violation yang disediakan dalam callback berasal dari
Throwable, dan stack trace tertutup menyediakan konteks penggunaan.
Pengujian menggunakan alat veridex
Anda juga dapat menggunakan alat analisis statis veridex pada APK. Alat veridex ini akan memindai seluruh codebase APK, termasuk setiap library pihak ketiga, lalu melaporkan semua penggunaan antarmuka non-SDK yang ditemukannya.
Keterbatasan alat veridex meliputi hal-hal berikut:
- Veridex tidak dapat mendeteksi pemanggilan melalui JNI.
- Veridex hanya dapat mendeteksi sebagian pemanggilan melalui refleksi.
- Analisis veridex untuk jalur kode yang tidak aktif terbatas pada pemeriksaan API level.
- Veridex hanya dapat dijalankan di perangkat yang mendukung petunjuk SSE4.2 dan POPCNT.
Windows
Biner Windows native tidak disediakan, tetapi Anda dapat menjalankan alat veridex di Windows dengan menjalankan biner Linux menggunakan Windows Subsystem for Linux (WSL). Sebelum mengikuti langkah-langkah di bagian ini, instal WSL dan pilih Ubuntu sebagai distribusi Linux Anda.
Setelah Ubuntu terinstal, buka terminal Ubuntu lalu ikuti langkah-langkah berikut:
- Download alat veridex dari repositori bawaan Android runtime.
- Ekstrak konten file
appcompat.tar.gz. - Dalam folder yang baru diekstrak, temukan
veridex-linux.zipdan ekstrak file tersebut. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan
your-app.apkadalah APK yang ingin Anda uji:./appcompat.sh --dex-file=your-app.apk
macOS
Untuk menjalankan alat veridex di macOS, ikuti langkah-langkah berikut:
- Download alat veridex dari repositori bawaan Android runtime.
- Ekstrak konten file
appcompat.tar.gz. - Dalam folder yang baru diekstrak, temukan
veridex-mac.zipdan ekstrak file tersebut. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan
/path-from-root/your-app.apkadalah jalur ke APK yang ingin Anda uji, dimulai dari direktori utama sistem Anda:./appcompat.sh --dex-file=/path-from-root/your-app.apk
Linux
Untuk menjalankan alat veridex di Linux, ikuti langkah-langkah berikut:
- Download alat veridex dari repositori bawaan Android runtime.
- Ekstrak konten file
appcompat.tar.gz. - Dalam folder yang baru diekstrak, temukan
veridex-linux.zipdan ekstrak file tersebut. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan
your-app.apkadalah APK yang ingin Anda uji:./appcompat.sh --dex-file=your-app.apk
Pengujian menggunakan alat lint Android Studio
Setiap kali Anda membangun aplikasi di Android Studio, alat lint akan memeriksa kode Anda untuk menemukan potensi masalah. Jika aplikasi Anda menggunakan antarmuka non-SDK, Anda mungkin melihat error atau peringatan build, tergantung dari daftar mana antarmuka tersebut berasal.
Anda juga dapat menjalankan alat lint dari command line atau menjalankan pemeriksaan secara manual pada project, folder, atau file tertentu.
Pengujian menggunakan Konsol Play
Saat diupload ke jalur pengujian di Konsol Play, aplikasi Anda akan otomatis diuji untuk menemukan potensi masalah, dan laporan pra-peluncuran akan dibuat. Jika aplikasi Anda menggunakan antarmuka non-SDK, error atau peringatan akan ditampilkan dalam laporan pra-peluncuran, tergantung dari daftar mana antarmuka tersebut berasal.
Untuk mengetahui informasi selengkapnya, lihat bagian Kompatibilitas Android dalam Menggunakan laporan pra-peluncuran untuk mengidentifikasi masalah.
Meminta API publik baru
Jika tidak dapat menemukan alternatif penggunaan antarmuka non-SDK untuk suatu fitur dalam aplikasi, Anda dapat meminta API publik baru dengan membuat permintaan fitur di issue tracker kami.
Saat membuat permintaan fitur, berikan informasi berikut:
- API yang saat ini Anda gunakan tetapi tidak didukung, termasuk deskripsi lengkap
yang terlihat dalam pesan logcat
Accessing hidden .... - Alasan Anda harus menggunakan API ini, termasuk detail fitur tingkat tinggi yang memerlukan API, bukan detail mendasarnya saja.
- Alasan API SDK publik terkait tidak mencukupi untuk tujuan Anda.
- Alternatif lain yang telah Anda coba dan alasan ketidakberhasilannya.
Saat memberikan detail ini dalam permintaan fitur, Anda memperbesar kemungkinan API publik baru akan diberikan.
Pertanyaan lainnya
Bagian ini mencakup beberapa jawaban untuk pertanyaan lain yang sering diajukan developer:
Pertanyaan umum
Bagaimana Google menjamin dapat memenuhi kebutuhan semua aplikasi melalui issuetracker?
Kami membuat daftar awal untuk Android 9 (level API 28) melalui analisis statis aplikasi, yang juga didukung dengan metode berikut:
- pengujian manual atas aplikasi-aplikasi populer di Google Play dan aplikasi di luar Google Play
- laporan internal
- pengumpulan data otomatis dari pengguna internal
- laporan pratinjau developer
- analisis statis tambahan yang dirancang untuk secara ketat menyertakan positif palsu (PP) lainnya
Saat mengevaluasi daftar untuk setiap rilis baru, kami mempertimbangkan penggunaan API serta masukan developer melalui issue tracker.
Bagaimana cara mengaktifkan akses ke antarmuka non-SDK?
Anda dapat mengaktifkan akses ke antarmuka non-SDK pada perangkat pengembangan menggunakan perintah adb untuk mengubah kebijakan penerapan API. Perintah yang digunakan bervariasi menurut level API. Perintah ini tidak memerlukan perangkat yang telah di-root.
- Android 10 (level API 29) atau yang lebih tinggi
Untuk mengaktifkan akses, gunakan perintah adb
berikut:
adb shell settings put global hidden_api_policy 1
Untuk mereset kebijakan penerapan API ke setelan default, gunakan perintah berikut:
adb shell settings delete global hidden_api_policy
- Android 9 (level API 28)
Untuk mengaktifkan akses, gunakan perintah adb berikut:
adb shell settings put global hidden_api_policy_pre_p_apps 1adb shell settings put global hidden_api_policy_p_apps 1Untuk mereset kebijakan penerapan API ke setelan default, gunakan perintah berikut:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
Anda dapat menetapkan bilangan bulat dalam kebijakan penerapan API ke salah satu nilai berikut:
- 0: Menonaktifkan semua deteksi antarmuka non-SDK. Menggunakan setelan ini akan menonaktifkan semua pesan log untuk penggunaan antarmuka non-SDK dan tidak mengizinkan Anda menguji aplikasi menggunakan
StrictModeAPI. Setelan ini tidak direkomendasikan. - 1: Mengaktifkan akses ke semua antarmuka non-SDK, tetapi menampilkan pesan log yang
berisi peringatan untuk setiap penggunaan antarmuka non-SDK. Penggunaan setelan ini juga memungkinkan Anda
menguji aplikasi menggunakan
StrictModeAPI. - 2: Melarang penggunaan antarmuka non-SDK yang termasuk dalam daftar yang tidak diizinkan atau diblokir bersyarat untuk level API target Anda.
Pertanyaan tentang daftar antarmuka non-SDK
Di mana saya dapat menemukan daftar API non-SDK pada image sistem?
Daftar tersebut dienkode dalam bit tanda akses kolom dan metode di file dex platform. Tidak ada file terpisah di image sistem yang berisi daftar ini.
Apakah daftar API non-SDK tetap sama di perangkat OEM yang berbeda dengan versi Android yang sama?
OEM dapat menambahkan antarmukanya sendiri ke daftar yang tidak diizinkan (daftar hitam), tetapi tidak dapat menghapus antarmuka dari daftar API non-SDK AOSP. CDD mencegah perubahan tersebut dan pengujian CTS memastikan bahwa Android Runtime menerapkan daftarnya.
Pertanyaan tentang kompatibilitas aplikasi terkait
Apakah ada batasan pada antarmuka non-NDK di kode native?
Android SDK mencakup antarmuka Java. Platform ini mulai membatasi akses ke antarmuka non-NDK untuk kode C/C++ native di Android 7 (level API 26). Untuk mengetahui informasi selengkapnya, lihat Meningkatkan Stabilitas dengan Pembatasan Simbol C/C++ Pribadi di Android N.
Apakah ada rencana untuk membatasi manipulasi file dex2oat atau DEX?
Kami tidak memiliki rencana aktif untuk membatasi akses ke biner dex2oat, tetapi kami tidak bermaksud untuk menjadikan format file DEX stabil atau menjadikannya antarmuka publik di luar bagian-bagian yang secara publik telah ditentukan dalam format Dalvik Executable. Kami berhak untuk memodifikasi atau menghilangkan dex2oat dan bagian-bagian dari format DEX yang belum ditentukan kapan saja. Perlu diperhatikan juga bahwa file turunan yang dihasilkan oleh dex2oat, seperti ODEX (juga dikenal sebagai OAT), VDEX, dan CDEX, semuanya merupakan format yang belum ditentukan.
Bagaimana jika SDK pihak ketiga yang penting (contohnya, obfuscator) tidak dapat menghindari penggunaan antarmuka non-SDK, tapi berkomitmen untuk menjaga kompatibilitasnya dengan versi Android mendatang? Dalam hal ini, dapatkah Android mengesampingkan persyaratan kompatibilitasnya?
Kami tidak berencana untuk mengesampingkan persyaratan kompatibilitas per SDK. Jika developer SDK hanya dapat mempertahankan kompatibilitas dengan bergantung pada antarmuka yang ada dalam daftar yang tidak didukung (sebelumnya abu-abu), mereka harus mulai merencanakan migrasi ke antarmuka SDK atau alternatif lainnya, serta meminta API publik baru setiap kali tidak dapat menemukan alternatif untuk penggunaan antarmuka non-SDK.
Apakah batasan antarmuka non-SDK berlaku untuk semua aplikasi, seperti aplikasi sistem serta aplikasi pihak pertama, bukan hanya aplikasi pihak ketiga?
Ya, tetapi kami mengecualikan aplikasi yang ditandatangani dengan kunci platform dan beberapa aplikasi image
sistem. Perlu diperhatikan bahwa pengecualian ini hanya berlaku untuk aplikasi yang merupakan bagian dari image
sistem (atau aplikasi image sistem yang diupdate). Daftar ini hanya ditujukan bagi aplikasi
yang dibuat untuk API platform pribadi, bukan API SDK
(dengan LOCAL_PRIVATE_PLATFORM_APIS := true).