Memecahkan masalah layanan latar depan

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

Dokumen ini membahas masalah berikut:

Sebelum Anda memecahkan masalah

Memeriksa perubahan terbaru pada layanan latar depan

Jika digunakan secara tidak tepat, 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 Anda mengalami masalah dengan layanan latar depan, sebaiknya periksa dokumentasi perubahan pada layanan latar depan dan lihat apakah ada perubahan terbaru yang dapat menjelaskan masalah Anda. Sangat penting untuk memeriksa perubahan dalam keadaan berikut:

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

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. Saat waktu habis, 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 memicu error Aplikasi Tidak Merespons.

Mendiagnosis:

Jika ANR disebabkan oleh layanan latar depan yang gagal berhenti sendiri, sistem akan menampilkan pengecualian internal. Anda dapat memverifikasi bahwa ini adalah masalahnya dengan memeriksa laporan ANR. Jika ini masalahnya, laporan akan 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 dengan batas waktu menyelesaikan tugasnya dan memanggil stopForeground(int) dalam batas waktu sistem.

Minta layanan latar depan Anda menerapkan Service.onTimeout(int,int). Pastikan penerapan metode tersebut segera 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 bahwa aplikasi telah berhenti.

Dalam beberapa kasus, sistem menampilkan pengecualian internal. Dalam kasus tersebut, Anda dapat mengetahui pengecualiannya dengan melihat pelacakan tumpukan, dan Anda dapat memeriksa Logcat untuk mengetahui informasi error yang lebih mendetail.

Internal exception: Timeout exceeded

Sistem memberlakukan batas durasi layanan latar depan sinkronisasi data dan pemrosesan media dapat berjalan saat aplikasi berada di latar belakang. Jika layanan melebihi 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 RemoteServiceException internal yang menyebabkan aplikasi error.

Mendiagnosis:

Anda dapat mengetahui pengecualiannya dengan melihat pelacakan tumpukan, dan Anda dapat memeriksa Logcat untuk mendapatkan informasi error yang lebih mendetail. Dalam hal ini, Logcat memiliki pesan error 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 dengan batas waktu menyelesaikan tugasnya dan memanggil stopForeground(int) dalam batas waktu sistem.

Minta layanan latar depan Anda menerapkan Service.onTimeout(int,int). Pastikan penerapan metode tersebut segera 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, layanan akan menampilkan ForegroundServiceDidNotStartInTimeException internal.

Mendiagnosis:

Anda dapat mengetahui pengecualiannya dengan melihat pelacakan tumpukan, dan Anda dapat memeriksa Logcat untuk mendapatkan informasi error yang lebih mendetail. Dalam hal ini, Logcat memiliki pesan error berikut:

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.

WorkManager:

Anda juga dapat melihat pengecualian ini dengan worker WorkManager yang menjalankan layanan latar depan (memanggil setForegound atau setForegroundAsync). Jika siklus proses dua worker latar depan tumpang-tindih saat satu worker mencoba memulai layanan latar depan sementara layanan latar depan yang berjalan sebelumnya mencoba dimatikan, error ini akan disertai dengan log berikut:

Re-initializing SystemForegroundService after a request to shut-down

Perbaikan untuk error ini diperkenalkan di WorkManager versi 2.10.5.

Jika aplikasi Anda mengalami pengecualian ini, update ke versi WorkManager terbaru dan laporkan masalah yang masih ada ke issue tracker WorkManager.

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 (level API 31), aplikasi tidak diizinkan untuk memulai layanan latar depan saat aplikasi berjalan di latar belakang, dengan beberapa pengecualian khusus. 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 kasus ini, ada bahaya bahwa pengguna mungkin mengklik tombol, lalu segera menempatkan aplikasi di latar belakang. Kemudian, 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 prioritas tinggi. Jika Anda 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 oleh aplikasi, periksa dokumentasi perubahan pada layanan latar depan dan konfirmasi bahwa 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 pastikan aplikasi Anda memenuhi salah satu pengecualian.

Anda dapat menggunakan komponen berbasis siklus proses untuk mengelola siklus proses aplikasi agar 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 aplikasi menargetkan Android 9 (level API 28) atau yang lebih tinggi, aplikasi tersebut harus memiliki izin FOREGROUND_SERVICE untuk meluncurkan layanan latar depan.
  • Jika aplikasi menargetkan Android 14 (level API 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 khusus). 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.