Penguatan audio latar belakang

Mulai Android 17, framework audio menerapkan batasan pada interaksi audio di latar belakang, termasuk pemutaran audio, permintaan fokus audio, dan API perubahan volume untuk memastikan bahwa perubahan ini dimulai secara 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 berjenis SHORT_SERVICE. Hal ini berlaku terlepas dari apakah aplikasi menargetkan level API 37 atau tidak.

Jika aplikasi menargetkan Android 17 (API level 37), ada batasan tambahan. Jika aplikasi 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 kemampuan WIU tidak berlaku jika aplikasi telah diberi izin alarm tepat, dan aplikasi tersebut membuat perubahan pada aliran audio yang memiliki atribut USAGE_ALARM.

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

Alasan kami melakukan perubahan ini

Tujuan dari pengenalan batasan ini adalah untuk mengurangi pengalaman audio latar belakang yang tidak disengaja dan penuh bug. Contohnya antara lain:

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

Kami mendorong developer untuk menguji aplikasi mereka dan memberikan masukan terkait perubahan perilaku jika ada kasus penggunaan audio yang disengaja dan berdampak negatif. Laporkan masalah apa pun menggunakan pelacak masalah kompatibilitas aplikasi Android 17 ini.

Mengidentifikasi kasus penggunaan audio latar belakang yang terpengaruh

Periksa penerapan pemutaran audio Anda dan identifikasi apakah aplikasi Anda bermaksud menyediakan fungsi interaksi audio di 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), maka aplikasi tersebut tidak terpengaruh oleh perubahan ini.

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

Jika aplikasi Anda bermaksud melanjutkan pemutaran audio saat layar mati atau saat aktivitas Anda tidak terlihat, yang paling sering terlihat di aplikasi streaming musik atau aplikasi podcast, maka 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 untuk melanjutkan interaksi audio yang dimulai saat aplikasi Anda terbuka, atau sebagai respons terhadap pemicu pengguna yang eksplisit, kemungkinan fungsi aplikasi Anda akan dibatalkan secara diam-diam.

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

Praktik terbaik audio latar belakang untuk mengurangi dampak

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

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

• Jika tidak menggunakan library media3, Anda harus memulai FGS mediaPlayback 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 kemampuan yang memungkinkan pengguna melanjutkan pemutaran saat layar mati, 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.

• Aktifkan mediaPlayback FGS selama kegagalan sementara kurang dari 10 menit.

  Jika aplikasi Anda mengalami kegagalan sementara, seperti masalah buffering karena aktivitas jaringan, atau ada gangguan sementara yang diharapkan seperti AUDIOFOCUS_LOSS_TRANSIENT, maksud untuk memutar harus dilanjutkan. Oleh karena itu, FGS Anda harus 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 pemutaran 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 hal ini sesuai dengan konsepsi pengguna tentang "menyelesaikan" interaksi audio latar belakang yang diinginkan. Setelah melakukannya, aplikasi Anda tidak lagi memiliki kemampuan interaksi audio di latar belakang.

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

• Uji perilaku pemutaran audio dengan perintah shell adb.

Menguji perubahan

Anda dapat menguji kepatuhan aplikasi Anda pada aplikasi yang berjalan di Android 17 atau yang lebih tinggi (mulai dengan 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 terlepas dari apakah aplikasi menargetkan Android 17 (level API 37). Selain itu, persyaratan ini diterapkan meskipun aplikasi membuat perubahan pada aliran alarm dan memiliki izin alarm yang tepat.

• disable: Menonaktifkan semua batasan penguatan audio.

• throw: Mengaktifkan semua batasan penguatan audio untuk semua aplikasi, seperti enable. Selain itu, tanda ini memungkinkan kegagalan yang jelas, yang memunculkan IllegalStateException untuk interaksi volume dan fokus. Untuk pemutaran audio, metode penulisan 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 yang diawali dengan AudioHardening dengan 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

Secara umum, layanan latar depan (FGS) harus diluncurkan saat aplikasi berada di latar depan untuk memperpanjang 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 Saat-Sedang-Digunakan (WIU).

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

Berikut referensi praktisnya:

• FGS Standar: Layanan yang dimulai saat aplikasi terlihat atau diberi kemampuan peluncuran aktivitas latar belakang 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 eksplisit pengguna, misalnya, klik notifikasi, interaksi widget, atau peristiwa tombol media dari perangkat eksternal.
• FGS dimulai sistem: Layanan latar depan diberi akses WIU jika dimulai oleh delegasi system-server (misalnya, dari library Jetpack Telecom), atau oleh binding sistem yang merepresentasikan status latar depan yang ditingkatkan untuk melakukan fungsi khusus (seperti untuk VoiceInteractionService).

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

Daftar lengkap API Audio yang terpengaruh