Ikuti serangkaian webinar gratis untuk membantu mengembangkan bisnis Anda di Google Play. Daftar sekarang

Batasan terkait antarmuka Non-SDK

Mulai dari Android 9 (API level 28), platform membatasi antarmuka non-SDK mana yang dapat digunakan aplikasi Anda. Pembatasan ini berlaku setiap kali aplikasi menggunakan antarmuka non-SDK atau mencoba untuk mendapatkan handle-nya menggunakan refleksi atau JNI. Pembatasan ini diterapkan untuk membantu meningkatkan pengalaman pengguna dan developer dan mengurangi risiko masalah bagi pengguna, serta isu darurat saat peluncuran bagi developer. Untuk informasi lebih lanjut tentang keputusan ini, lihat 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 API, sehingga antarmuka ini dapat berubah tanpa pemberitahuan.

Untuk menghindari masalah 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.

Blacklist, greylist, dan whitelist

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 baru.

Untuk meminimalkan dampak pembatasan non-SDK pada alur kerja pengembangan Anda, antarmuka non-SDK dibagi ke dalam daftar yang menentukan seberapa ketat penggunaannya dibatasi, tergantung pada level API mana yang ditargetkan. Tabel berikut menjelaskan masing-masing daftar ini:

Daftar Deskripsi
Blacklist Antarmuka non-SDK yang tidak dapat digunakan, apa pun level API target aplikasi Anda. Jika aplikasi Anda mencoba mengakses salah satu antarmuka ini, sistem akan memberikan pesan error.
Greylist Antarmuka non-SDK yang dapat digunakan selama mereka tidak dibatasi untuk level API target aplikasi Anda.

Mulai dari Android 9 (API level 28), setiap level API memiliki antarmuka non-SDK yang dibatasi pada level API itu. Meskipun API greylist yang dibatasi ini dapat diakses jika aplikasi Anda menargetkan level API yang lebih rendah, jika aplikasi Anda mencoba mengakses antarmuka non-SDK yang dibatasi untuk level API target Anda, maka sistem akan berperilaku seolah-olah API di-blacklist.

Catatan: Di Android 9 (API level 28), antarmuka non-SDK dari greylist yang tidak dibatasi disebut daftar lightgrey, sedangkan antarmuka non-SDK dari greylist yang dibatasi disebut daftar darkgrey.

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

Meskipun saat ini Anda dapat menggunakan beberapa antarmuka non-SDK greylist (tergantung pada level API target aplikasi Anda), namun menggunakan metode atau kolom non-SDK selalu berisiko tinggi merusak aplikasi Anda. Jika aplikasi Anda mengandalkan antarmuka non-SDK, Anda harus mulai merencanakan migrasi ke antarmuka SDK atau alternatif lainnya. Jika Anda tidak dapat menemukan alternatif penggunaan antarmuka non-SDK untuk sebuah fitur di aplikasi Anda, Anda sebaiknya meminta API publik baru.

Menentukan daftar untuk antarmuka

Daftar antarmuka non-SDK dibuat sebagai bagian dari platform ini.

Untuk Android 9 (API level 28), file teks ini berisi daftar API greylist yang tidak dibatasi. Blacklist dan greylist yang dibatasi diambil dari waktu pembuatan. Ada aturan pembuatan yang menghasilkan daftar tersebut di AOSP. Meskipun daftar AOSP tersebut tidak sama dengan daftar untuk Android 9, kemiripannya cukup tinggi. Anda juga dapat membuat blacklist sendiri dengan mendownload AOSP kemudian menjalankan perintah berikut:

    make hiddenapi-aosp-blacklist
    

Anda kemudian dapat menemukan file-nya di lokasi berikut:

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

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 blacklist.

Cara akses Hasil
Instruksi Dalvik merujuk sebuah kolom NoSuchFieldError muncul
Instruksi Dalvik merujuk sebuah metode NoSuchMethodError muncul
Refleksi melalui Class.getDeclaredField() atau Class.getField() NoSuchFieldException muncul
Refleksi melalui Class.getDeclaredMethod(), Class.getMethod() NoSuchMethodException muncul
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 dihasilkan, NoSuchFieldError muncul
JNI melalui env->GetMethodID() NULL dihasilkan, NoSuchMethodError muncul

Menguji aplikasi untuk antarmuka non-SDK

Ada beberapa metode yang dapat digunakan untuk menguji antarmuka non-SDK di aplikasi Anda.

Uji menggunakan aplikasi yang dapat di-debug

Anda dapat menguji antarmuka non-SDK dengan mem-build dan menjalankan aplikasi yang dapat di-debug pada sebuah perangkat atau emulator yang menjalankan Android 9 (API level 28) atau lebih tinggi. Pastikan perangkat atau emulator yang Anda gunakan cocok dengan level API target aplikasi Anda.

Saat menjalankan pengujian pada aplikasi Anda, sistem akan mencetak pesan log jika aplikasi Anda mengakses antarmuka non-SDK tertentu. Anda dapat memeriksa pesan log aplikasi Anda untuk menemukan detail berikut:

  • Class, nama, dan tipe yang menyatakan (dalam format yang digunakan oleh runtime Android).
  • Cara akses: baik secara linking, melalui refleksi, atau melalui JNI.
  • Daftar yang menyertakan antarmuka non-SDK.

Anda dapat menggunakan adb logcat untuk mengakses pesan log ini, yang muncul di bawah PID dari aplikasi yang berjalan. Misalnya, entri dalam log mungkin berbunyi seperti berikut:

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

Uji menggunakan API StrictMode

Anda juga dapat menguji antarmuka non-SDK dengan API StrictMode. Gunakan metode detectNonSdkApiUsage untuk mengaktifkannya. Setelah mengaktifkan API StrictMode, Anda dapat menerima callback untuk setiap penggunaan antarmuka non-SDK menggunakan penaltyListener, tempat Anda dapat menerapkan penanganan khusus. Objek Violation yang tersedia dalam callback berasal dari Throwable, dan pelacakan tumpukan yang tertutup akan memberikan konteks penggunaannya.

Uji 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 level API.

Windows

Biner Windows asli 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 waktu proses Android.
  2. Ekstrak konten file appcompat.tar.gz.
  3. Dalam folder yang diekstrak, temukan veridex-linux.zip dan ekstrak file tersebut.
  4. Buka folder yang telah diekstrak lalu jalankan perintah berikut, dengan your-app.apk adalah APK yang ingin diuji:

        ./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 waktu proses Android.
  2. Ekstrak konten file appcompat.tar.gz.
  3. Dalam folder yang diekstrak, temukan veridex-mac.zip dan ekstrak file tersebut.
  4. Buka folder yang telah diekstrak lalu jalankan perintah berikut, dengan your-app.apk adalah APK yang ingin diuji:

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

Linux

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

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

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

Uji menggunakan alat lint Android Studio

Setiap kali Anda mem-build aplikasi di Android Studio, alat lint akan memeriksa kode Anda terhadap potensi masalah. Jika aplikasi menggunakan antarmuka non-SDK, Anda mungkin akan melihat error atau peringatan build, tergantung apakah antarmuka tersebut merupakan bagian dari daftar hitam atau greylist.

Anda juga dapat menjalankan alat lint dari command line atau menjalankan pemeriksaan secara manual pada project, folder, atau file tertentu.

Uji menggunakan Konsol Play

Saat Anda mengupload aplikasi ke track pengujian di Konsol Play, aplikasi akan diuji secara otomatis terhadap potensi masalah, dan laporan pra-peluncuran akan dibuat. Jika aplikasi menggunakan antarmuka non-SDK, error atau peringatan akan ditampilkan dalam laporan pra-peluncuran, tergantung apakah antarmuka tersebut merupakan bagian dari daftar hitam atau greylist.

Untuk mengetahui informasi selengkapnya, lihat bagian Kompatibilitas Android pada Menggunakan laporan pra-peluncuran untuk mengidentifikasi masalah.

Meminta API publik baru

Jika tidak dapat menemukan alternatif untuk penggunaan antarmuka non-SDK bagi fitur dalam aplikasi, Anda dapat membuat permintaan fitur untuk API publik baru agar ditambahkan ke SDK.

Saat membuat permintaan fitur, berikan informasi berikut ini:

  • API greylist mana yang Anda gunakan saat ini, termasuk keterangan lengkap yang terlihat di pesan logcat Accessing hidden ....
  • Mengapa Anda perlu menggunakan API ini, termasuk detail fitur tingkat tinggi yang diperlukan API, bukan hanya detail mendasarnya saja.
  • Mengapa API SDK publik terkait tidak mencukupi untuk tujuan Anda.
  • Alternatif lain yang telah Anda coba dan mengapa ini tidak berhasil.

Saat Anda 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 bisa yakin dapat memenuhi kebutuhan semua aplikasi melalui issuetracker?

Kami membuat daftar awal untuk Android 9 (API level 28) melalui analisis statis aplikasi yang juga dilengkapi 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 memasukkan false positive (positif palsu) lainnya

Saat kami mengevaluasi daftar untuk setiap rilis baru, kami mempertimbangkan penggunaan API akun serta masukan developer melalui pelacak masalah (issue tracker).

Bagaimana saya bisa mengaktifkan akses ke antarmuka non-SDK?

Anda dapat mengaktifkan akses ke antarmuka non-SDK pada perangkat pengembangan dengan mengubah kebijakan penerapan API menggunakan 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 mengatur ulang 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
    

Perintah ini tidak memerlukan perangkat yang telah di-root.

Anda dapat mengatur bilangan bulat di kebijakan penerapan API ke salah satu nilai berikut:

  • 0: Menonaktifkan semua deteksi antarmuka non-SDK. Setelan ini akan menonaktifkan semua pesan log untuk penggunaan antarmuka non-SDK dan mencegah Anda menguji aplikasi menggunakan API StrictMode. Setelan ini tidak direkomendasikan.
  • 1: Mengaktifkan akses ke semua antarmuka non-SDK, tetapi mencetak pesan log yang berisi peringatan untuk setiap penggunaan antarmuka non-SDK. Dengan setelan ini, Anda juga dapat menguji aplikasi menggunakan API StrictMode.
  • 2: Melarang penggunaan antarmuka non-SDK yang termasuk dalam blacklist atau greylist dan yang dibatasi untuk level API target Anda.
  • 3: Melarang penggunaan antarmuka non-SDK yang masuk ke blacklist, tapi mengizinkan penggunaan antarmuka yang masuk ke greylist dan dibatasi untuk level API 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 gambar sistem yang berisi daftar ini.

Apakah blacklist dan greylist sama pada perangkat OEM yang berbeda dengan versi Android yang sama?

OEM dapat menambahkan antarmuka mereka sendiri ke blacklist, tapi mereka tidak dapat menghapus antarmuka dari blacklist atau greylist AOSP. CDD mencegah perubahan tersebut dan tes CTS memastikan bahwa Android Runtime menerapkan daftar.

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 (API level 26). Untuk informasi lebih lanjut, 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, tapi 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. Harap perhatikan 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 (misalnya, obfuscator) tidak dapat menghindari penggunaan antarmuka non-SDK, tapi berkomitmen untuk menjaga kompatibilitasnya dengan versi Android mendatang? Dalam hal ini, bisakah Android mengesampingkan persyaratan kompatibilitasnya?

Kami tidak memiliki rencana untuk mengesampingkan persyaratan kompatibilitas berdasarkan masing-masing SDK. Jika satu developer SDK saat ini hanya dapat mempertahankan kompatibilitasnya dengan bergantung pada antarmuka di greylist, mereka harus mulai merencanakan migrasi ke antarmuka SDK atau alternatif lainnya, serta meminta API publik baru setiap kali mereka tidak dapat menemukan alternatif dari penggunaan antarmuka non-SDK.

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

Ya, tapi kami mengecualikan aplikasi yang ditandatangani dengan kunci platform, dan kami juga memiliki paket whitelist untuk beberapa aplikasi gambar sistem. Perhatikan bahwa pengecualian ini hanya berlaku untuk aplikasi yang merupakan bagian dari gambar sistem (atau aplikasi gambar sistem yang diupdate). Daftar ini ditujukan hanya bagi aplikasi yang di-build terhadap API platform pribadi, bukan API SDK (dengan LOCAL_PRIVATE_PLATFORM_APIS := true).