Android 11 memperkenalkan alat developer baru untuk menguji dan men-debug aplikasi Anda terhadap perubahan perilaku di platform Android versi lebih baru. Alat ini merupakan bagian dari framework kompatibilitas yang memungkinkan developer aplikasi mengaktifkan dan menonaktifkan satu per satu perubahan yang dapat menyebabkan gangguan menggunakan opsi developer atau ADB. Gunakan fleksibilitas ini saat Anda bersiap untuk menargetkan versi API stabil dan saat Anda menguji aplikasi dengan rilis pratinjau versi Android berikutnya.
Jika Anda menggunakan alat framework kompatibilitas, platform Android
secara otomatis menyesuaikan logika internalnya, sehingga Anda tidak perlu mengubah
targetSDKVersion
atau kompilasi ulang aplikasi Anda untuk melakukan pengujian dasar. Karena
perubahan dapat diubah satu per satu, Anda dapat mengisolasi, menguji, dan melakukan debug
perubahan perilaku pada satu waktu atau menonaktifkan
satu perubahan yang menyebabkan masalah jika
Anda perlu menguji
hal lain terlebih dahulu.
Cara mengidentifikasi perubahan yang diaktifkan
Saat diaktifkan, perubahan perilaku dapat memengaruhi cara aplikasi Anda mengakses API platform yang terpengaruh oleh perubahan tersebut. Anda dapat memeriksa perilaku mana perubahan diaktifkan menggunakan opsi developer, logcat, atau perintah ADB.
Mengidentifikasi perubahan yang saat ini aktif dengan opsi developer
![](https://developer.android.com/static/images/guide/app-compatibility/appcompat-dev-options.png?authuser=9&hl=id)
Gambar 1. Layar Perubahan Kompatibilitas Aplikasi di opsi developer.
Anda dapat melihat perubahan mana yang diaktifkan dan mengaktifkan atau menonaktifkan perubahan tersebut di opsi developer perangkat. Untuk mengakses opsi ini, ikuti langkah-langkah berikut:
- Aktifkan opsi developer, jika belum diaktifkan.
- Buka aplikasi Setelan di perangkat dan pilih Sistem > Lanjutan > Opsi developer > Perubahan Kompatibilitas Aplikasi.
Pilih aplikasi Anda dari daftar.
Setiap perubahan perilaku biasanya termasuk dalam salah satu dari dua kategori berikut:
Perubahan yang memengaruhi semua aplikasi yang berjalan pada versi Android tersebut, terlepas dari
targetSdkVersion
aplikasi.Perubahan ini diaktifkan secara default di framework kompatibilitas, dan dicantumkan di UI di bagian Perubahan Aktif Default.
Perubahan yang hanya memengaruhi aplikasi yang menargetkan versi Android tertentu. Karena perubahan ini hanya memengaruhi aplikasi yang menargetkan versi Android tertentu, perubahan tersebut juga disebut sebagai perubahan yang dibatasi oleh
targetSDKVersion
.Perubahan ini diaktifkan secara default dalam framework kompatibilitas jika aplikasi Anda menargetkan versi yang lebih tinggi daripada versi API yang tercantum. Misalnya, perubahan perilaku yang dibatasi oleh
targetSDKVersion
di Android 13 (level API 33) akan dicantumkan di UI bagian yang berjudul Diaktifkan untuk targetSdkVersion >=33. Pada beberapa versi Android yang lebih rendah, bagian ini berjudul "Diaktifkan Setelah SDK API_LEVEL" sebagai gantinya.
Anda juga akan melihat bagian pada gambar 1 yang disebut Perubahan Nonaktif Default. Perubahan yang termasuk dalam bagian ini dapat memenuhi berbagai tujuan. Sebelum pembaruan mengaktifkan perubahan ini, baca deskripsi perubahan di dokumen kompatibilitas daftar framework untuk versi Android tersebut.
Mengidentifikasi perubahan yang saat ini aktif menggunakan logcat
Untuk setiap perubahan perilaku, saat aplikasi Anda memanggil API yang terpengaruh untuk pertama kali dalam prosesnya, sistem akan menampilkan pesan logcat seperti berikut:
D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED
Setiap pesan logcat mencakup informasi berikut:
- Change ID
- Menunjukkan perubahan yang memengaruhi aplikasi. Nilai ini dipetakan ke salah satu
perubahan perilaku yang tercantum di layar Perubahan Kompatibilitas Aplikasi
(lihat gambar 1). Dalam contoh ini,
194833441
dipetakan keNOTIFICATION_PERM_CHANGE_ID
. - UID
- Menunjukkan aplikasi yang terpengaruh oleh perubahan tersebut.
- Status
Menunjukkan apakah perubahan memengaruhi aplikasi.
Status dapat berupa salah satu nilai berikut:
Status Arti ENABLED
Perubahan diaktifkan dan akan memengaruhi perilaku aplikasi jika aplikasi menggunakan API yang diubah. DISABLED
Perubahan dinonaktifkan dan tidak akan memengaruhi aplikasi.
Catatan: Jika perubahan ini dinonaktifkan karena
targetSDKVersion
aplikasi lebih rendah dari nilai minimum yang diwajibkan, perubahan akan diaktifkan secara default saat aplikasi meningkatkantargetSDKVersion
untuk menargetkan versi yang lebih tinggi.LOGGED
Perubahan dicatat ke dalam log melalui framework kompatibilitas, tetapi tidak dapat diaktifkan atau dinonaktifkan. Meskipun demikian, perubahan ini masih dapat memengaruhi perilaku aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat deskripsi perubahan di daftar framework kompatibilitas untuk versi Android tersebut. Sering kali jenis perubahan ini bersifat eksperimental dan dapat diabaikan.
Mengidentifikasi perubahan yang saat ini aktif menggunakan ADB
Jalankan perintah ADB berikut untuk melihat rangkaian perubahan lengkap (yang diaktifkan dan dinonaktifkan) di seluruh perangkat:
adb shell dumpsys platform_compat
Outputnya mencantumkan informasi berikut untuk setiap perubahan:
- Change ID
- ID unik untuk perubahan perilaku ini. Misalnya,
194833441
. - Name
- Nama perubahan perilaku. Misalnya,
NOTIFICATION_PERM_CHANGE_ID
. - targetSDKVersion criteria
targetSDKVersion
yang digunakan untuk membatasi perubahan (jika ada).Misalnya, jika perubahan ini hanya diaktifkan untuk aplikasi yang menargetkan versi SDK 33 atau lebih tinggi, output-nya adalah
enableAfterTargetSdk=32
. Jika perubahan bukan dibatasi olehtargetSDKVersion
,enableAfterTargetSdk=0
adalah output.- Penggantian paket
Nama setiap paket dengan status default perubahan (baik diaktifkan maupun dinonaktifkan) telah diganti.
Misalnya, jika perubahan diaktifkan secara default, nama paket aplikasi Anda akan dicantumkan jika Anda menonaktifkan perubahan menggunakan opsi developer atau ADB. Dalam hal ini, output-nya adalah:
packageOverrides={com.my.package=false}
Perubahan yang dibatasi oleh
targetSDKVersion
dapat diaktifkan atau dinonaktifkan secara {i>default<i}, sehingga daftar paket dapat menyertakan baik instancetrue
ataufalse
, bergantung padatargetSDKVersion
setiap aplikasi tersebut. Contoh:packageOverrides={com.my.package=true, com.another.package=false}
Mempelajari perubahan tertentu lebih lanjut
Daftar lengkap perubahan perilaku dalam framework kompatibilitas disertakan sebagai dokumentasi untuk setiap versi Android. Lihat tautan berikut untuk informasi selengkapnya, bergantung pada versi Android yang digunakan untuk menguji aplikasi untuk:
- Android 15 (level API 35)
- Android 14 (level API 34)
- Android 13 (level API 33)
- Android 12 (level API 31 dan 32)
- Android 11 (level API 30)
Waktu untuk mengganti status perubahan
Tujuan utama dari framework kompatibilitas ini adalah untuk memberikan kontrol dan fleksibilitas saat Anda menguji aplikasi dengan versi Android yang lebih baru. Bagian ini menjelaskan beberapa strategi yang dapat digunakan untuk menentukan kapan harus mengaktifkan atau menonaktifkan perubahan saat Anda menguji dan melakukan debug aplikasi.
Waktu untuk menonaktifkan perubahan
Menentukan waktu untuk menonaktifkan perubahan biasanya bergantung pada apakah perubahan
dibatasi oleh targetSDKVersion
atau tidak.
- Perubahan diaktifkan untuk semua aplikasi
Perubahan yang memengaruhi semua aplikasi diaktifkan oleh default untuk versi platform tertentu, apa pun aplikasi Anda
targetSDKVersion
, agar Anda dapat melihat apakah aplikasi terpengaruh dengan menjalankan aplikasi di versi platform tersebut.Misalnya, jika Anda bersiap untuk menargetkan Android 14 (level API 34), mulailah dengan menginstal aplikasi di perangkat yang menjalankan Android 14 dan menguji aplikasi Anda menggunakan alur kerja pengujian standar. Jika aplikasi Anda mengalami masalah, Anda dapat menonaktifkan perubahan yang menyebabkan masalah sehingga Anda dapat melanjutkan pengujian untuk masalah lainnya.
Karena perubahan ini dapat memengaruhi semua aplikasi terlepas dari
targetSDKVersion
, Anda biasanya harus menguji dan mengupdate aplikasi untuk perubahan ini sebelum perubahan yang dibatasi olehtargetSDKVersion
. Hal ini membantu memastikan bahwa pengguna Anda tidak akan mengalami penurunan kualitas pengalaman aplikasi saat mereka memperbarui perangkat ke versi baru versi platform.Anda juga harus memprioritaskan pengujian perubahan ini karena tidak dapat menonaktifkan perubahan ini saat menggunakan build rilis publik Android. Idealnya, Anda harus melakukan pengujian terhadap perubahan ini untuk setiap versi Android saat versi tersebut sedang dipratinjau.
- Perubahan dibatasi oleh
targetSDKVersion
Jika aplikasi Anda menargetkan
targetSDKVersion
, perubahan apa pun yang dibatasi oleh versi tersebut diaktifkan secara {i>default<i}. Jadi, saat Anda mengalihkantargetSDKVersion
aplikasi ke aplikasi Anda akan mulai terpengaruh oleh banyak perubahan baru sekaligus.Karena aplikasi Anda mungkin terpengaruh oleh lebih dari satu perubahan ini, Anda mungkin perlu menonaktifkan beberapa perubahan ini secara terpisah saat menguji dan melakukan debug aplikasi.
Waktu untuk mengaktifkan perubahan
Perubahan yang dibatasi oleh targetSDKVersion
tertentu dinonaktifkan secara default
setiap kali aplikasi menargetkan versi SDK yang lebih rendah dari versi yang dibatasi.
Biasanya, saat bersiap untuk menargetkan targetSdkVersion
baru, Anda akan memiliki daftar perubahan perilaku yang diperlukan sebagai tujuan dalam menguji dan men-debug aplikasi.
Misalnya, Anda mungkin akan menguji aplikasi terhadap serangkaian perubahan platform
pada targetSdkVersion
berikutnya. Menggunakan opsi developer atau perintah ADB, Anda
dapat mengaktifkan dan menguji setiap perubahan yang dibatasi satu per satu, bukan mengubah
manifes aplikasi dan memilih ikut serta dalam setiap perubahan sekaligus. Kontrol tambahan ini dapat membantu
Anda menguji perubahan secara terpisah serta menghindari proses debug dan update pada
beberapa bagian aplikasi sekaligus.
Setelah mengaktifkan perubahan, Anda dapat menguji dan melakukan debug aplikasi menggunakan alur kerja pengujian standar. Jika Anda mengalami masalah, periksa log untuk membantu menentukan penyebab masalah. Jika tidak jelas apakah masalahnya disebabkan oleh {i>platform <i}yang aktif, coba nonaktifkan perubahan itu lalu uji ulang area aplikasi Anda.
Mengaktifkan atau menonaktifkan perubahan
Framework kompatibilitas memungkinkan Anda mengaktifkan atau menonaktifkan setiap perubahan menggunakan opsi developer atau perintah ADB. Mengaktifkan atau menonaktifkan perubahan dapat menyebabkan error pada aplikasi atau menonaktifkan perubahan keamanan penting, sehingga ada beberapa pembatasan untuk mengganti status perubahan.
Mengganti status perubahan menggunakan opsi developer
Gunakan opsi developer untuk mengaktifkan atau menonaktifkan perubahan. Untuk menemukan opsi developer, ikuti langkah-langkah berikut:
- Aktifkan opsi developer, jika belum diaktifkan.
- Di aplikasi Setelan perangkat, buka Sistem > Lanjutan > Opsi developer > Perubahan Kompatibilitas Aplikasi.
- Pilih aplikasi Anda dari daftar.
Dari daftar perubahan, temukan perubahan yang ingin Anda aktifkan atau nonaktifkan, lalu ketuk tombolnya.
Beralih perubahan menggunakan ADB
Untuk mengaktifkan atau menonaktifkan perubahan menggunakan ADB, jalankan salah satu perintah berikut:
adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
Teruskan CHANGE_ID
(misalnya 194833441
) atau
CHANGE_NAME
(misalnya
NOTIFICATION_PERM_CHANGE_ID
) beserta
PACKAGE_NAME
aplikasi Anda.
Anda juga dapat menggunakan perintah berikut untuk mereset perubahan kembali ke status defaultnya, yang akan menghapus semua penggantian yang telah ditetapkan menggunakan ADB atau opsi developer:
adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
Pembatasan dalam mengganti status perubahan
Secara default, setiap perubahan perilaku akan diaktifkan atau dinonaktifkan. Perubahan yang
memengaruhi semua aplikasi diaktifkan secara default. Perubahan lainnya dibatasi oleh targetSdkVersion
. Perubahan ini diaktifkan secara default saat aplikasi menargetkan versi SDK yang sesuai atau yang lebih tinggi, dan dinonaktifkan secara default saat aplikasi menargetkan versi SDK yang lebih rendah dari versi yang dibatasi. Saat mengaktifkan atau menonaktifkan
perubahan, Anda akan mengganti status default-nya.
Agar framework kompatibilitas tidak digunakan secara tidak benar, ada beberapa pembatasan untuk mengganti status perubahan. Apakah Anda dapat beralih perubahan bergantung pada jenis perubahan, apakah aplikasi Anda dapat di-debug, dan jenis build yang berjalan di perangkat Anda. Tabel berikut menjelaskan kapan Anda diizinkan untuk mengganti berbagai jenis perubahan:
Jenis build | Aplikasi yang tidak dapat di-debug | Aplikasi yang dapat di-debug | |
---|---|---|---|
Semua perubahan | Perubahan yang dibatasi oleh targetSDKVersion | Semua perubahan lainnya | |
Pratinjau Developer atau versi Beta | Tidak dapat beralih | Dapat beralih | Dapat beralih |
Versi pengguna publik | Tidak dapat beralih | Dapat beralih | Tidak dapat beralih |