Memecahkan masalah layanan latar depan

Halaman ini membahas beberapa alasan umum layanan latar depan dapat gagal 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 melakukan perubahan pada perilaku layanan latar depan untuk membatasi efek buruk ini.

Jika Anda 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. Anda harus 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 Anda

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

Error Aplikasi Tidak Merespons (ANR)

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

Layanan singkat berjalan terlalu lama, menyebabkan ANR

Layanan latar depan yang menggunakan jenis layanan singkat harus diselesaikan dengan cepat, dalam waktu sekitar tiga menit. Saat waktu habis, sistem akan memanggil metode layanan Service.onTimeout(int,int). 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 dengan sendirinya, sistem akan menampilkan pengecualian internal. Anda dapat memverifikasi bahwa ini adalah masalahnya dengan memeriksa laporan ANR. Jika ini adalah 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 pekerjaannya dan memanggil stopForeground(int) dalam batas waktu sistem.

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

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 akan menampilkan pengecualian internal. Dalam kasus tersebut, Anda dapat mengetahui pengecualiannya dengan melihat pelacakan stack, dan Anda dapat memeriksa Logcat untuk mengetahui informasi error yang lebih mendetail.

Pengecualian internal: Waktu tunggu habis

Sistem menetapkan batas waktu 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 membuat RemoteServiceException internal yang menyebabkan aplikasi mengalami error.

Mendiagnosis:

Anda dapat mengetahui pengecualiannya dengan melihat pelacakan stack, dan Anda dapat memeriksa Logcat untuk 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 pekerjaannya dan memanggil stopForeground(int) dalam batas waktu sistem.

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

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, akan menampilkan ForegroundServiceDidNotStartInTimeException internal.

Mendiagnosis:

Anda dapat mengetahui pengecualiannya dengan melihat pelacakan stack, dan Anda dapat memeriksa Logcat untuk 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 mungkin juga melihat pengecualian ini dengan pekerja WorkManager yang menjalankan layanan latar depan (memanggil setForegound atau setForegroundAsync). Jika siklus proses dua pekerja latar depan tumpang-tindih saat satu pekerja mencoba memulai layanan latar depan sementara layanan latar depan yang sebelumnya berjalan mencoba untuk 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 terus berlanjut ke pelacak masalah 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 tertentu. Jika Anda mencoba memulai layanan latar depan dari latar belakang dan Anda tidak memenuhi persyaratan salah satu pengecualian, sistem akan menampilkan ForegroundServiceStartNotAllowedException. Sistem juga melakukan hal ini 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 dapat mengklik tombol, lalu segera menempatkan aplikasi di latar belakang. Aplikasi kemudian 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 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 sehingga 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 berbasis siklus proses 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 aplikasi menargetkan Android 9 (level API 28) atau yang lebih tinggi, aplikasi 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 kepada aplikasi saat aplikasi berada di latar depan (dengan beberapa pengecualian tertentu). Artinya, meskipun aplikasi Anda telah meminta dan diberikan 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 permissions.
    • Anda mungkin mendapatkan SecurityException jika Anda meminta izin yang diperlukan, tetapi Anda 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.