Penguatan audio latar belakang

Mulai Android 17, framework audio menerapkan batasan pada interaksi audio latar belakang, termasuk pemutaran audio, permintaan fokus audio, dan API perubahan volume untuk memastikan bahwa perubahan ini dimulai dengan sengaja oleh pengguna.

Semua aplikasi yang berjalan di Android 17 yang memiliki interaksi audio latar belakang ini harus memiliki aktivitas yang terlihat atau harus menjalankan layanan latar depan yang bukan jenis SHORT_SERVICE. Hal ini berlaku baik aplikasi menargetkan API level 37 atau tidak.

Jika aplikasi menargetkan Android 17 (level API 37), ada batasan tambahan. Jika berjalan di latar belakang, aplikasi harus menjalankan layanan latar depan yang memiliki kemampuan saat digunakan (WIU). (Layanan latar depan diberi kemampuan WIU jika dimulai sebagai respons terhadap operasi yang dimulai pengguna atau saat aplikasi terlihat oleh pengguna.) Namun, persyaratan untuk kemampuan WIU ditiadakan jika aplikasi telah diberi izin alarm presisi, dan aplikasi tersebut membuat perubahan pada streaming audio yang memiliki atribut USAGE_ALARM.

Jika aplikasi mencoba memanggil API audio saat aplikasi tidak berada dalam siklus proses yang valid, API pemutaran audio dan perubahan volume akan gagal secara otomatis tanpa menampilkan pengecualian atau memberikan pesan kegagalan. API fokus audio gagal dengan kode hasil AUDIOFOCUS_REQUEST_FAILED.

Alasan kami melakukan perubahan ini

Tujuan diperkenalkannya batasan ini adalah untuk mengurangi pengalaman audio latar belakang yang bermasalah dan tidak disengaja. Contohnya antara lain:

• Aplikasi yang memutar audio tanpa layanan latar depan dapat dibekukan. Saat aplikasi akhirnya dicairkan, aplikasi akan melanjutkan pemutaran audio secara tidak terduga, yang berpotensi terjadi beberapa jam kemudian.
• Aplikasi yang memutar audio tanpa layanan latar depan menghadapi berbagai batasan operasi yang mengakibatkan performa audio yang tidak stabil.
• Pemutaran terlepas dari siklus proses aktivitas, yang dapat mengakibatkan kebocoran sesi pemutaran atau kebocoran peristiwa fokus yang berlanjut tanpa cara bagi pengguna untuk menghentikan pemutaran.

Sebaiknya developer menguji aplikasi mereka dan memberikan masukan terkait perubahan perilaku jika ada kasus penggunaan audio yang disengaja dan terkena dampak negatif. Laporkan masalah apa pun menggunakan issue tracker kompatibilitas aplikasi Android 17 ini.

Mengidentifikasi kasus penggunaan audio latar belakang yang terpengaruh

Audit implementasi pemutaran audio Anda dan identifikasi apakah aplikasi Anda bermaksud menyediakan fungsi interaksi audio latar belakang bahkan dalam keadaan bersyarat.

Jika aplikasi Anda hanya bermaksud memutar audio atau menggunakan API audio saat menampilkan aktivitas yang terlihat oleh pengguna, termasuk menggunakan mode Picture in Picture (PiP), aplikasi tersebut tidak akan terpengaruh oleh perubahan ini.

Jika aplikasi Anda menyediakan fungsi VOIP, termasuk aplikasi panggilan video, aplikasi tersebut harus sudah memenuhi persyaratan yang diperkenalkan untuk pemutaran (biasanya melalui penggunaan API telekomunikasi yang direkomendasikan) agar berhasil merekam audio, sehingga kemungkinan tidak akan terpengaruh.

Jika aplikasi Anda bermaksud melanjutkan pemutaran audio saat layar nonaktif atau saat aktivitas Anda tidak terlihat, yang paling sering terlihat di aplikasi streaming musik atau aplikasi podcast, aplikasi Anda dianggap menyediakan fungsi audio latar belakang dan harus memenuhi persyaratan baru.

Skenario audio latar belakang yang kemungkinan akan terpengaruh

Jika aplikasi Anda tidak mengikuti model melanjutkan interaksi audio yang dimulai saat aplikasi terbuka, atau sebagai respons terhadap pemicu pengguna yang eksplisit, kemungkinan fungsi aplikasi Anda akan disembunyikan secara otomatis.

Misalnya, jika aplikasi Anda memulai layanan latar depan sebagai respons terhadap BOOT_COMPLETE dan mencoba berinteraksi dengan audio, layanan tersebut akan ditiadakan.

Praktik terbaik audio latar belakang untuk mengurangi dampak

• Gunakan komponen MediaSessionService library jetpack media3 untuk mengelola pemutaran audio latar belakang.

  Jika Anda melakukannya, aplikasi Anda kemungkinan tidak akan terpengaruh oleh penguatan latar belakang karena library membantu mengelola siklus proses pemutaran.

• Jika tidak memanfaatkan library media3, Anda harus memulai mediaPlayback FGS secara manual. Selalu mulai layanan latar depan saat aplikasi berada di latar depan jika audio latar belakang dapat terjadi.

  Misalnya, jika aplikasi Anda adalah aplikasi streaming video yang biasanya hanya berjalan di latar depan, tetapi berisi affordance pengguna untuk terus memutar saat layar nonaktif, maka saat pemicu pemutaran yang dimulai pengguna terjadi, aplikasi Anda tetap harus memulai layanan latar depan.

  Tindakan ini memastikan bahwa layanan latar depan dimulai dengan kemampuan WIU.

• Tetap aktifkan mediaPlayback FGS selama kegagalan sementara yang berlangsung kurang dari 10 menit.

  Jika aplikasi Anda mengalami kegagalan sementara, seperti masalah buffering karena aktivitas jaringan, atau ada gangguan sementara yang diperkirakan seperti AUDIOFOCUS_LOSS_TRANSIENT, intent untuk memutar harus dilanjutkan. Dengan demikian, FGS Anda akan tetap aktif.

• Hentikan layanan latar depan di akhir pemutaran dan mulai ulang pemutaran hanya jika pengguna secara eksplisit melanjutkan pemutaran.

  Jika ada sinyal permanen untuk mengakhiri pemutaran (misalnya, konten selesai tanpa putar otomatis, AUDIOFOCUS_LOSS, peristiwa jeda dari UMO, atau peristiwa tombol media) atau kegagalan yang tidak dapat dipulihkan, aplikasi Anda harus menghentikan interaksi audio, menghentikan layanan latar depan, dan mengakhiri sesi media. Melakukan semua ini sesuai dengan konsepsi pengguna tentang "menyelesaikan" interaksi audio latar belakang yang diinginkan. Setelah melakukan ini, aplikasi Anda tidak lagi memiliki kemampuan interaksi audio latar belakang.

  Selanjutnya, jika pengguna secara eksplisit melanjutkan pemutaran, misalnya melalui UI aplikasi Anda atau melalui tombol putar Objek Media Universal, intent untuk memulai pemutaran audio akan ditampilkan, sehingga menghasilkan FGS yang baru dimulai.

• Menguji perilaku pemutaran audio dengan perintah shell adb.

Menguji perubahan

Anda dapat menguji kepatuhan aplikasi pada aplikasi yang menjalankan Android 17 atau yang lebih baru (mulai dari Beta 3) dengan menjalankan perintah ADB berikut:

adb shell cmd audio set-enable-hardening <enable|disable|throw>

Perintah ini memiliki opsi berikut:

• enable: Mengaktifkan semua batasan penguatan audio untuk semua aplikasi. Persyaratan untuk layanan latar depan WIU diterapkan, baik aplikasi menargetkan Android 17 (level API 37) maupun tidak. Selain itu, persyaratan ini diberlakukan meskipun aplikasi membuat perubahan pada streaming alarm dan memiliki izin alarm presisi.

• disable: Menonaktifkan semua pembatasan penguatan audio.

• throw: Mengaktifkan semua batasan penguatan audio untuk semua aplikasi, seperti enable. Selain itu, flag ini memungkinkan kegagalan yang jelas, yang menampilkan IllegalStateException untuk interaksi volume dan fokus. Untuk pemutaran audio, metode tulis terus-menerus menampilkan kode error. Untuk mode pemutaran tanpa penulisan eksplisit, aplikasi akan error.

Gunakan adb dumpsys audio atau logcat untuk mengidentifikasi apakah aplikasi mengalami kegagalan senyap karena penerapan penguatan audio. Jika ya, akan ada entri dengan awalan AudioHardening yang berisi nama paket Anda. Jika pesan berisi level: full, aplikasi Anda menjalankan layanan latar depan, tetapi layanan tersebut tidak memiliki kemampuan saat digunakan. Jika pesan berisi level: partial, aplikasi Anda tidak menjalankan layanan latar depan sama sekali.

Memahami FGS dengan kemampuan saat digunakan

Umumnya, layanan latar depan (FGS) harus diluncurkan saat aplikasi berada di latar depan untuk memperluas operasi yang dimulai pengguna. Dalam beberapa kasus tertentu, aplikasi diizinkan untuk meluncurkan layanan latar depan saat aplikasi berada di latar belakang. Namun, layanan latar depan ini biasanya tidak diberi kemampuan While-In-Use (WIU).

WIU bertindak sebagai gerbang keamanan–mencegah FGS yang dimulai dari latar belakang melakukan perilaku sensitif tertentu saat pengguna mungkin tidak menyadari aktivitas aplikasi. Mode ini mencegah aplikasi mengakses data sensitif seperti lokasi, kamera, atau mikrofon, dan mulai Android 17, mode ini juga memblokir API audio yang biasanya memerlukan konteks UI yang terlihat.

Berikut referensi yang berguna:

• FGS standar: Layanan yang dimulai saat aplikasi terlihat atau diberi kemampuan peluncuran aktivitas latar belakang akan diberi akses WIU.
• FGS yang Dimulai di Latar Belakang (BFSL): Sebagian besar tidak memberikan akses WIU. Pengecualian utama yang memberikan WIU adalah interaksi yang melibatkan niat pengguna yang eksplisit, misalnya, klik notifikasi, interaksi widget, atau peristiwa tombol media dari perangkat eksternal.
• FGS yang dimulai sistem: Layanan latar depan diberi akses WIU jika dimulai oleh delegasi server sistem (misalnya, dari library jetpack Telecom), atau oleh binding sistem yang mewakili status latar depan yang ditingkatkan untuk menjalankan fungsi khusus (seperti untuk VoiceInteractionService).

Baca selengkapnya di Batasan untuk memulai layanan latar depan dari latar belakang.

Daftar lengkap Audio API yang terpengaruh