Memecahkan masalah layanan latar depan

Halaman ini membahas beberapa alasan umum kegagalan layanan latar depan dan membantu Anda mengidentifikasi penyebab masalah.

Dokumen ini membahas masalah berikut:

Sebelum Anda memecahkan masalah

Memeriksa perubahan terbaru pada layanan latar depan

Jika digunakan dengan tidak benar, layanan latar depan dapat berdampak negatif pada performa perangkat dan masa pakai baterai. Oleh karena itu, rilis platform Android sering kali membuat perubahan pada perilaku layanan latar depan untuk membatasi efek buruk ini.

Jika mengalami masalah dengan layanan latar depan, Anda harus memeriksa dokumentasi perubahan pada layanan latar depan dan melihat apakah ada perubahan terbaru yang dapat menjelaskan masalah Anda. Penting untuk memeriksa perubahan dalam keadaan berikut:

  • Kode layanan latar depan yang sebelumnya berfungsi kini gagal
  • Anda baru saja mulai menguji pada rilis platform baru, atau Anda telah mengubah level API yang ditargetkan oleh aplikasi

Selain itu, jika Anda menguji perangkat pada pratinjau developer platform, pastikan untuk memeriksa versi terbaru dokumentasi pratinjau developer.

Error Aplikasi Tidak Merespons (ANR)

Dalam situasi tertentu, aplikasi diharapkan untuk menonaktifkan layanan latar depannya. Jika aplikasi tidak menghentikan layanan, sistem akan menghentikan layanan dan memicu error Aplikasi Tidak Merespons (ANR).

Layanan singkat berjalan terlalu lama sehingga menyebabkan ANR

Layanan latar depan yang menggunakan jenis layanan singkat harus selesai dengan cepat, dalam waktu sekitar tiga menit. Jika waktu habis, sistem akan memanggil metode Service.onTimeout(int,int) layanan. Layanan memiliki beberapa detik untuk memanggil stopSelf(). Jika layanan tidak berhenti dengan sendirinya, sistem akan memicu error Aplikasi Tidak Merespons.

Diagnosa:

Jika ANR disebabkan oleh layanan latar depan yang gagal menghentikan dirinya sendiri, sistem akan menampilkan pengecualian internal. Anda dapat memverifikasi bahwa ini adalah masalahnya dengan memeriksa Logcat. Dalam hal ini, log menyertakan pesan berikut:

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type FOREGROUND_SERVICE_TYPE_SHORT_SERVICE did not stop within its timeout:
[component name]"

Perbaikan:

Pastikan semua layanan latar depan berbatas waktu menyelesaikan tugasnya dan memanggil stopForeground(int) dalam batas waktu sistem.

Minta layanan latar depan Anda menerapkan Service.onTimeout(int,int). Pastikan implementasi metode tersebut langsung memanggil stopSelf().

Pengecualian layanan latar depan

Bagian ini menjelaskan beberapa masalah layanan latar depan yang dapat menyebabkan sistem menampilkan pengecualian. Jika aplikasi tidak menangkap pengecualian, pengguna akan melihat dialog yang memberi tahu mereka bahwa aplikasi telah berhenti.

Dalam beberapa kasus, sistem akan menampilkan pengecualian internal. Anda tidak dapat menangkap pengecualian tersebut, tetapi Anda dapat melihat di Logcat untuk melihat pengecualian yang ditampilkan.

Pengecualian internal: Waktu tunggu terlampaui

Sistem memberlakukan batas durasi layanan latar depan sinkronisasi data dan pemrosesan media dapat berjalan saat aplikasi berada di latar belakang. Jika layanan melampaui batas tersebut, sistem akan memanggil metode Service.onTimeout(int,int) layanan. Layanan memiliki waktu beberapa detik untuk memanggil stopSelf(). Jika layanan tidak berhenti dengan sendirinya, sistem akan menghasilkan pengecualian internal yang menyebabkan aplikasi error.

Diagnosa:

Jika penyebabnya adalah waktu tunggu terlampaui, Logcat akan menyertakan pesan berikut:

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type [service type] did not stop within its timeout: [component name]"

Perbaikan:

Pastikan semua layanan latar depan berbatas waktu menyelesaikan tugasnya dan memanggil stopForeground(int) dalam batas waktu sistem.

Minta layanan latar depan Anda menerapkan Service.onTimeout(int,int). Pastikan implementasi metode tersebut langsung memanggil stopSelf().

Pengecualian internal: ForegroundServiceDidNotStartInTimeException

Saat Anda meluncurkan layanan dengan memanggil context.startForegroundService(), layanan tersebut memiliki waktu beberapa detik untuk mempromosikan dirinya ke layanan latar depan dengan memanggil ServiceCompat.startForeground(). Jika layanan tidak melakukannya, sistem akan memicu error ANR.

Diagnosa:

Jika layanan latar depan tidak dimulai tepat waktu, aplikasi akan error, sehingga pengguna melihat dialog Aplikasi telah berhenti. Dalam hal ini, Anda dapat menemukan pesan berikut di Logcat:

android.app.RemoteServiceException$ForegroundServiceDidNotStartInTimeException:
Context.startForegroundService() did not then call Service.startForeground()

Perbaikan:

Pastikan semua layanan latar depan yang baru dibuat memanggil ServiceCompat.startForeground() dalam beberapa detik.

ForegroundServiceStartNotAllowedException

Error:

Sistem menampilkan ForegroundServiceStartNotAllowedException.

Penyebab:

Hal ini biasanya disebabkan oleh aplikasi yang meluncurkan layanan latar depan dari latar belakang saat tidak ada pengecualian yang valid.

Mulai Android 12 (API level 31), aplikasi tidak diizinkan untuk memulai layanan latar depan saat aplikasi berjalan di latar belakang, dengan beberapa pengecualian tertentu. Jika Anda mencoba memulai layanan latar depan dari latar belakang dan tidak memenuhi persyaratan salah satu pengecualian, sistem akan menampilkan ForegroundServiceStartNotAllowedException. Sistem juga akan melakukannya jika Anda tidak memenuhi persyaratan pengecualian.

Misalnya, aplikasi mungkin memiliki tombol yang dapat diklik pengguna, yang menyebabkan aplikasi melakukan beberapa pemrosesan, lalu meluncurkan layanan latar depan. Dalam hal ini, ada bahaya bahwa pengguna mungkin mengklik tombol, lalu langsung menempatkan aplikasi di latar belakang. Dalam hal ini, aplikasi akan mencoba meluncurkan layanan dari latar belakang. Jika aplikasi tidak memenuhi salah satu pengecualian yang ditentukan, sistem akan menampilkan ForegroundServiceStartNotAllowedException.

Selain itu, beberapa pengecualian memiliki batas waktu yang singkat. Misalnya, ada pengecualian singkat jika aplikasi Anda meluncurkan layanan latar depan sebagai respons terhadap pesan FCM berprioritas tinggi. Jika tidak meluncurkan layanan dengan cukup cepat, Anda akan mendapatkan ForegroundServiceStartNotAllowedException.

Pengecualian tertentu terkadang menjadi lebih ketat dengan rilis Android baru. Jika Anda telah mengubah versi Android yang ditargetkan aplikasi, periksa dokumentasi perubahan pada layanan latar depan dan pastikan aplikasi Anda masih memenuhi salah satu pengecualian yang diizinkan.

Perbaikan:

Ubah alur kerja aplikasi Anda agar tidak perlu meluncurkan layanan latar depan saat aplikasi berada di latar belakang, atau konfirmasi bahwa aplikasi Anda memenuhi salah satu pengecualian.

Anda dapat menggunakan komponen siklus proses seperti LiveData untuk mengelola siklus proses aplikasi sehingga Anda tidak secara tidak sengaja mencoba meluncurkan layanan latar depan dari latar belakang.

SecurityException

Error:

Sistem menampilkanSecurityException.

Penyebab:

Aplikasi Anda mencoba meluncurkan layanan latar depan tanpa memiliki izin yang diperlukan.

  • Jika menargetkan Android 9 (API level 28) atau yang lebih tinggi, aplikasi harus memiliki izin FOREGROUND_SERVICE untuk meluncurkan layanan latar depan.
  • Jika menargetkan Android 14 (API level 34) atau yang lebih tinggi, aplikasi harus memenuhi semua prasyarat untuk jenis layanan latar depannya. Prasyarat ini dijelaskan dalam dokumentasi jenis layanan latar depan. Secara khusus, perhatikan persyaratan berikut:
    • Beberapa jenis layanan latar depan memerlukan izin runtime tertentu. Misalnya, layanan latar depan pesan jarak jauh harus memiliki izin FOREGROUND_SERVICE_REMOTE_MESSAGING.
  • Dalam beberapa kasus, ada batasan tambahan saat digunakan pada izin yang diperlukan oleh beberapa jenis layanan latar depan. Izin ini hanya diberikan ke aplikasi saat aplikasi berada di latar depan (dengan beberapa pengecualian tertentu). Artinya, meskipun aplikasi Anda telah meminta dan diberi salah satu izin ini, jika aplikasi mencoba meluncurkan layanan latar depan saat aplikasi berada di latar belakang, sistem akan menampilkan SecurityException meskipun aplikasi memiliki pengecualian untuk memulai layanan latar depan dari latar belakang. Untuk mengetahui informasi selengkapnya, lihat Batasan untuk memulai layanan latar depan yang memerlukan izin saat digunakan.
    • Anda mungkin mendapatkan SecurityException jika meminta izin yang diperlukan, tetapi memulai layanan latar depan sebelum mengonfirmasi bahwa izin yang diperlukan telah diberikan.

Perbaikan:

Sebelum meluncurkan layanan latar depan, minta semua izin layanan latar depan yang sesuai, dan konfirmasi bahwa Anda telah memenuhi semua prasyarat runtime lainnya.