Batasan terkait antarmuka Non-SDK

Mulai Android 9 (API level 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 tak terduga, aplikasi hanya dapat menggunakan bagian class yang didokumentasikan secara resmi di SDK. Ini juga berarti bahwa Anda tidak dapat mengakses metode atau kolom yang tidak tercantum dalam SDK ketika Anda berinteraksi dengan class melalui mekanisme seperti refleksi.

Daftar hitam, daftar abu-abu, dan daftar putih

Dengan setiap rilis Android, antarmuka non-SDK tambahan akan dibatasi. Kami tahu pembatasan ini dapat memengaruhi alur kerja rilis Anda, dan kami ingin memastikan 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 API level yang ditargetkan. Tabel berikut menjelaskan masing-masing daftar ini:

Daftar Deskripsi
Daftar hitam 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.
Daftar abu-abu Antarmuka non-SDK yang dapat digunakan, asalkan tidak dibatasi untuk API level target aplikasi Anda.

Mulai Android 9 (API level 28), setiap API level memiliki antarmuka non-SDK yang dibatasi pada API level tersebut. Meskipun API daftar abu-abu yang dibatasi ini dapat diakses jika aplikasi Anda menargetkan API level yang lebih rendah, tetap saja sistem akan berperilaku seolah-olah API diblokir jika aplikasi Anda mencoba mengakses antarmuka non-SDK yang dibatasi untuk API level target Anda.

Catatan: Di Android 9 (API level 28), antarmuka non-SDK dari daftar abu-abu yang tidak dibatasi disebut daftar abu-abu terang, sedangkan antarmuka non-SDK dari daftar abu-abu yang dibatasi disebut daftar abu-abu gelap.

Daftar putih Antarmuka yang dapat digunakan secara bebas dan didukung sebagai bagian dari Indeks Paket framework Android yang didokumentasikan secara resmi.

Meskipun Anda saat ini dapat menggunakan beberapa antarmuka non-SDK yang termasuk dalam daftar abu-abu (bergantung pada API level target aplikasi Anda), menggunakan metode atau kolom non-SDK tetap akan berisiko menimbulkan error pada aplikasi. Jika aplikasi Anda bergantung pada antarmuka non-SDK, mulailah merencanakan migrasi ke antarmuka SDK atau alternatif lainnya. Jika tidak dapat menemukan alternatif penggunaan antarmuka non-SDK untuk suatu fitur dalam aplikasi, Anda harus meminta API publik baru.

Menentukan daftar untuk antarmuka

Daftar antarmuka non-SDK dibuat sebagai bagian dari platform ini. Lihat bagian di bawah untuk mengetahui informasi tentang setiap rilis Android.

Android 10

Untuk Android 10 (API level 29), file berikut menjelaskan semua antarmuka non-SDK dan daftar yang terkait dengannya: hiddenapi-flags.csv.

Android 9

Untuk Android 9 (API level 28), file teks berikut berisi daftar API yang termasuk dalam daftar abu-abu yang tidak dibatasi: hiddenapi-light-greylist.txt.

Daftar hitam dan daftar abu-abu yang dibatasi 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 dengannya. 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

Tabel berikut menjelaskan perilaku yang akan terjadi jika aplikasi Anda mencoba mengakses antarmuka non-SDK yang merupakan bagian dari daftar hitam.

Cara akses Hasil
Petunjuk Dalvik yang merujuk sebuah kolom NoSuchFieldError ditampilkan
Petunjuk Dalvik yang merujuk sebuah metode NoSuchMethodError ditampilkan
Refleksi melalui Class.getDeclaredField() atau Class.getField() NoSuchFieldException ditampilkan
Refleksi melalui Class.getDeclaredMethod(), Class.getMethod() NoSuchMethodException ditampilkan
Refleksi melalui Class.getDeclaredFields(), Class.getFields() Anggota non-SDK tidak ada dalam hasil
Refleksi melalui Class.getDeclaredMethods(), Class.getMethods() Anggota non-SDK tidak ada dalam hasil
JNI melalui env->GetFieldID() NULL ditunjukkan, NoSuchFieldError ditampilkan
JNI melalui 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 membuat dan menjalankan aplikasi yang dapat di-debug di perangkat atau emulator yang menjalankan Android 9 (API level 28) atau yang lebih baru. Pastikan perangkat atau emulator yang Anda gunakan sesuai dengan API level 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 runtime Android).
  • Cara akses: baik secara penautan, melalui refleksi, atau melalui 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 pelacakan tumpukan tertutup menyediakan konteks penggunaan.

Pengujian menggunakan alat veridex

Anda juga dapat menggunakan alat analisis statis veridex pada APK. Alat veridex ini akan memindai seluruh code base 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 invocation melalui JNI.
  • Veridex hanya dapat mendeteksi sebagian invocation 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, luncurkan terminal Ubuntu lalu ikuti langkah-langkah berikut:

  1. Download alat veridex dari repositori bawaan runtime Android.
  2. Ekstrak konten file appcompat.tar.gz.
  3. Dalam folder yang baru diekstrak, temukan veridex-linux.zip dan ekstrak file tersebut.
  4. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan your-app.apk adalah APK yang ingin Anda uji:

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

macOS

Untuk menjalankan alat veridex di macOS, ikuti langkah-langkah berikut:

  1. Download alat veridex dari repositori bawaan runtime Android.
  2. Ekstrak konten file appcompat.tar.gz.
  3. Dalam folder yang baru diekstrak, temukan veridex-mac.zip dan ekstrak file tersebut.
  4. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan /path-from-root/your-app.apk adalah 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:

  1. Download alat veridex dari repositori bawaan runtime Android.
  2. Ekstrak konten file appcompat.tar.gz.
  3. Dalam folder yang baru diekstrak, temukan veridex-linux.zip dan ekstrak file tersebut.
  4. Buka folder yang sudah diekstrak, lalu jalankan perintah berikut, dengan your-app.apk adalah APK yang ingin Anda uji:

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

Pengujian menggunakan alat lint Android Studio

Setiap kali Anda membuat aplikasi di Android Studio, alat lint akan memeriksa kode Anda untuk menemukan potensi masalah. Jika aplikasi menggunakan antarmuka non-SDK, Anda mungkin akan melihat error atau peringatan build, bergantung apakah antarmuka tersebut merupakan bagian dari daftar hitam atau daftar abu-abu.

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 Anda mengupload aplikasi ke track pengujian di Konsol Play, aplikasi akan otomatis diuji untuk menemukan potensi masalah, dan laporan pra-peluncuran akan dibuat. Jika aplikasi menggunakan antarmuka non-SDK, error atau peringatan akan ditampilkan dalam laporan pra-peluncuran, bergantung apakah antarmuka tersebut merupakan bagian dari daftar hitam atau daftar abu-abu.

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, 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 digunakan yang termasuk dalam daftar abu-abu, termasuk deskripsi lengkap yang ditampilkan di 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 akan memenuhi kebutuhan semua aplikasi melalui issuetracker?

Kami membuat daftar awal untuk Android 9 (API level 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 API level. Perintah ini tidak memerlukan perangkat yang telah di-root.

Android 10 (API level 29)

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 (API level 28)

Untuk mengaktifkan akses, gunakan perintah adb berikut:

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

Untuk mereset kebijakan penerapan API ke setelan default, gunakan perintah berikut:

adb shell settings delete global hidden_api_policy_pre_p_apps
adb 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 StrictMode API. 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 memungkinkan Anda menguji aplikasi menggunakan StrictMode API.
  • 2: Melarang penggunaan antarmuka non-SDK yang termasuk dalam daftar hitam atau daftar abu-abu, dan yang dibatasi untuk API level target Anda.

Pertanyaan tentang daftar antarmuka non-SDK

Di mana saya dapat menemukan blacklist dan greylist di gambar sistem?

Daftar-daftar ini dikodekan dalam kolom dan bit access flag di file dex platform. Tidak ada file terpisah di image sistem yang berisi daftar ini.

Apakah daftar hitam dan daftar abu-abu akan tetap sama di perangkat OEM yang berbeda dengan versi Android yang sama?

OEM dapat menambahkan antarmukanya sendiri ke daftar hitam, tetapi tidak dapat menghapus antarmuka dari daftar hitam atau daftar abu-abu AOSP. CDD mencegah perubahan tersebut dan pengujian CTS memastikan bahwa Android Runtime menerapkan daftar.

Apakah ada batasan untuk antarmuka non-NDK dalam kode native?

Android SDK mencakup antarmuka Java. Platform ini mulai membatasi akses ke antarmuka non-NDK untuk kode C/C++ native di Android 7 (API level 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 memiliki rencana untuk mengesampingkan persyaratan kompatibilitas berdasarkan masing-masing SDK. Jika seseorang developer SDK saat ini hanya dapat mempertahankan kompatibilitas dengan bergantung pada antarmuka yang ada dalam daftar abu-abu, dia harus mulai merencanakan migrasi ke antarmuka SDK atau alternatif lainnya, serta meminta API publik baru setiap kali mereka tidak dapat menemukan alternatif untuk penggunaan antarmuka non-SDK.

Apakah pembatasan 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 kami juga memiliki daftar putih paket untuk 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).