Alat framework kompatibilitas

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 menargetkan versi API stabil terbaru dan saat menguji aplikasi dengan rilis pratinjau versi Android berikutnya.

Saat Anda menggunakan alat framework kompatibilitas, platform Android akan otomatis menyesuaikan logika internalnya, sehingga Anda tidak perlu mengubah targetSDKVersion atau mengompilasi ulang aplikasi untuk melakukan pengujian dasar. Karena perubahan dapat diganti statusnya satu per satu, Anda dapat mengisolasi, menguji, dan melakukan debug perubahan perilaku satu per satu 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 perubahan perilaku mana yang diaktifkan menggunakan opsi developer, logcat, atau perintah ADB.

Mengidentifikasi perubahan yang saat ini aktif dengan opsi developer

Gambar 1. Layar Perubahan Kompatibilitas Aplikasi di opsi developer.

Anda dapat melihat perubahan yang diaktifkan dan mengaktifkan atau menonaktifkan perubahan tersebut di opsi developer perangkat. Untuk mengakses opsi ini, ikuti langkah-langkah berikut:

1. Aktifkan opsi developer, jika belum diaktifkan.
2. Buka aplikasi Setelan di perangkat dan pilih Sistem > Lanjutan > Opsi developer > Perubahan Kompatibilitas Aplikasi.

3. Pilih aplikasi Anda dari daftar.

   Catatan: Anda harus menggunakan varian build yang dapat di-debug dari aplikasi untuk mengaktifkan dan menonaktifkan perubahan.

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 di bagian berjudul Diaktifkan untuk targetSdkVersion >=33. Di beberapa versi Android yang lebih rendah, bagian ini diberi judul "Diaktifkan Setelah SDK API_LEVEL".

  Catatan: Selama pratinjau Android 15 hingga API level selesai, beberapa perubahan yang hanya diaktifkan saat menargetkan Android 15 menggunakan nilai 10000 untuk API level, bukan API level dugaan akhir 35.

Anda juga akan melihat bagian pada gambar 1 yang disebut Perubahan Nonaktif Default. Perubahan yang termasuk dalam bagian ini dapat memenuhi berbagai tujuan. Sebelum mengaktifkan perubahan ini, baca deskripsi perubahan di daftar framework kompatibilitas 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

Catatan: Setiap perubahan hanya dicatat dalam log maksimal sekali per proses. Paksa berhenti dan mulai ulang proses aplikasi untuk memastikan Anda melihat semua pesan logcat yang relevan.

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 ke NOTIFICATION_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 meningkatkan targetSDKVersion 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 yang lebih tinggi, output-nya adalah enableAfterTargetSdk=32. Jika perubahan tidak dibatasi oleh targetSDKVersion, output-nya adalah enableAfterTargetSdk=0.

Penggantian paket

Nama setiap paket dengan status default perubahan (baik diaktifkan maupun dinonaktifkan) yang 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 default, sehingga daftar paket dapat menyertakan instance true atau false, bergantung pada targetSDKVersion 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 bagian dari dokumentasi untuk setiap versi Android. Lihat link berikut untuk informasi selengkapnya, bergantung pada versi Android yang digunakan untuk menguji aplikasi:

• 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 secara default untuk versi platform tertentu, apa pun targetSDKVersion aplikasi. Anda dapat melihat apakah aplikasi terpengaruh dengan menjalankan aplikasi di versi platform tersebut.

Misalnya, jika Anda bersiap untuk menargetkan Android 15 (level API 35), mulailah dengan menginstal aplikasi di perangkat yang menjalankan Android 15 dan menguji aplikasi Anda menggunakan alur kerja pengujian standar. Jika aplikasi mengalami masalah, Anda dapat menonaktifkan perubahan yang menyebabkan masalah sehingga 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 oleh targetSDKVersion. Hal ini membantu memastikan bahwa pengguna tidak akan mengalami penurunan pengalaman aplikasi saat mengupdate perangkat mereka ke versi platform baru.

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 tertentu, perubahan apa pun yang dibatasi oleh versi tersebut diaktifkan secara default. Jadi, saat Anda mengalihkan targetSDKVersion aplikasi ke versi baru, 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 masalah disebabkan oleh perubahan platform yang diaktifkan atau tidak, coba nonaktifkan perubahan tersebut, kemudian uji kembali area tersebut pada 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.

Catatan: Setiap kali Anda mengganti status perubahan untuk suatu aplikasi menggunakan opsi developer atau perintah ADB, proses aplikasi akan dihentikan agar penggantian yang dilakukan dapat segera diterapkan.

Mengganti status perubahan menggunakan opsi developer

Gunakan opsi developer untuk mengaktifkan atau menonaktifkan perubahan. Untuk menemukan opsi developer, ikuti langkah-langkah berikut:

1. Aktifkan opsi developer, jika belum diaktifkan.
2. Di aplikasi Setelan perangkat, buka Sistem > Lanjutan > Opsi developer > Perubahan Kompatibilitas Aplikasi.
3. Pilih aplikasi Anda dari daftar.

4. 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. Penggantian status 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