Alat framework kompatibilitas

Android 11 memperkenalkan alat developer baru untuk menguji dan melakukan debug aplikasi Anda terhadap perubahan perilaku di platform Android versi 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.

Platform Android 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

Anda dapat memeriksa perubahan perilaku mana yang saat ini 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 saat ini diaktifkan dan mengaktifkan atau menonaktifkannya di opsi developer pada 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.

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 11 (API level 30) akan dicantumkan di UI di bagian Diaktifkan Setelah SDK 29.

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: 119147584; UID 10265; state: ENABLED

Setiap pesan logcat mencakup informasi berikut:

ID Perubahan
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, 119147584 dipetakan ke CALLBACK_ON_CLEAR_CHANGE.
UID
Menunjukkan aplikasi yang terpengaruh oleh perubahan tersebut.
Status

Menunjukkan apakah perubahan saat ini memengaruhi aplikasi.

Status dapat berupa salah satu nilai berikut:

Status Arti
ENABLED Perubahan saat ini diaktifkan dan akan memengaruhi perilaku aplikasi jika aplikasi menggunakan API yang diubah.
DISABLED

Perubahan saat ini 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:

ID Perubahan
ID unik untuk perubahan perilaku ini. Contoh, 119147584.
Nama
Nama perubahan perilaku. Contoh, CALLBACK_ON_CLEAR_CHANGE.
Kriteria targetSDKVersion

targetSDKVersion dengan perubahan yang dibatasi (jika ada).

Misalnya, jika perubahan ini hanya diaktifkan untuk aplikasi yang menargetkan versi SDK 30 atau yang lebih tinggi, output-nya adalah enableAfterTargetSdk=29. 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, tergantung 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:

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, terlepas dari targetSDKVersion aplikasi. Anda dapat melihat apakah aplikasi terpengaruh dengan menjalankan aplikasi di versi platform tersebut.

Misalnya, jika Anda bersiap untuk menargetkan Android 11 (API level 30), mulailah dengan menginstal aplikasi di perangkat yang menjalankan Android 11 dan menguji aplikasi Anda menggunakan alur kerja pengujian standar. Jika aplikasi mengalami masalah, Anda dapat menonaktifkan perubahan yang menyebabkan masalah agar 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 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 Anda bersiap untuk menargetkan targetSdkVersion baru, Anda akan memiliki daftar perubahan perilaku yang memerlukan pengujian dan debug pada 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.

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.

    Daftar perubahan yang dapat diaktifkan atau dinonaktifkan

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 119147584) atau CHANGE_NAME (misalnya CALLBACK_ON_CLEAR_CHANGE) 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 dilindungi 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 dilindungi. 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 dilindungi oleh targetSDKVersion Semua perubahan lainnya
Pratinjau Developer atau versi Beta Tidak dapat beralih Dapat beralih Dapat beralih
Build pengguna publik Tidak dapat beralih Dapat beralih Tidak dapat beralih