Jenis layanan latar depan

Mulai Android 14 (level API 34), Anda harus mendeklarasikan jenis layanan yang sesuai untuk setiap layanan latar depan. Artinya, Anda harus mendeklarasikan jenis layanan dalam manifes aplikasi, dan juga meminta izin layanan latar depan yang sesuai untuk jenis tersebut (selain meminta izin FOREGROUND_SERVICE). Selain itu, bergantung pada jenis layanan latar depan, Anda mungkin harus meminta izin runtime sebelum meluncurkan layanan.

Kamera

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian android:foregroundServiceType
camera
Izin yang akan dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_CAMERA
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Prasyarat runtime

Meminta dan mendapatkan izin runtime CAMERA

Deskripsi

Terus mengakses kamera dari latar belakang, seperti aplikasi video chat yang memungkinkan multitasking.

Perangkat yang terhubung

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
connectedDevice
Izin untuk dideklarasikan dalam manifes
FOREGROUND_SERVICE_CONNECTED_DEVICE
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Prasyarat runtime

Setidaknya salah satu syarat berikut harus terpenuhi:

Deskripsi

Interaksi dengan perangkat eksternal yang memerlukan Bluetooth, NFC, IR, USB, atau koneksi jaringan.

Alternatif

Jika aplikasi Anda perlu melakukan transfer data berkelanjutan ke perangkat eksternal, pertimbangkan untuk menggunakan pengelola perangkat pendamping. Gunakan API kehadiran perangkat pendamping untuk membantu aplikasi Anda tetap berjalan saat perangkat pendamping berada dalam jangkauan.

Jika aplikasi Anda perlu memindai perangkat Bluetooth, sebaiknya gunakan Bluetooth scan API.

Sinkronisasi data

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di
android:foregroundServiceType
dataSync
Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_DATA_SYNC
Konstanta untuk diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Prasyarat runtime
Tidak ada
Deskripsi

Operasi transfer data, seperti berikut:

  • Upload atau download data
  • Operasi pencadangan dan pemulihan
  • Operasi impor atau ekspor
  • Mengambil data
  • Pemrosesan file lokal
  • Mentransfer data antara perangkat dan cloud melalui jaringan
Alternatif

Lihat Alternatif untuk layanan latar depan sinkronisasi data untuk mengetahui informasi mendetail.

Kesehatan

Jenis layanan latar depan yang akan dideklarasikan dalam manifes
android:foregroundServiceType
health
Izin yang akan dideklarasikan dalam manifes
FOREGROUND_SERVICE_HEALTH
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Prasyarat runtime

Setidaknya salah satu syarat berikut harus terpenuhi:

Deskripsi

Semua kasus penggunaan yang berjalan lama untuk mendukung aplikasi dalam kategori kebugaran seperti pelacak latihan.

Lokasi

Jenis layanan latar depan yang akan dideklarasikan dalam manifes
android:foregroundServiceType
location
Izin untuk dideklarasikan dalam manifes
FOREGROUND_SERVICE_LOCATION
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Prasyarat runtime

Pengguna harus telah mengaktifkan layanan lokasi dan aplikasi harus diberi setidaknya salah satu izin runtime berikut:

Deskripsi

Kasus penggunaan jangka panjang yang memerlukan akses lokasi, seperti navigasi dan berbagi lokasi.

Alternatif

Jika aplikasi Anda perlu dipicu saat pengguna mencapai lokasi tertentu, pertimbangkan untuk menggunakan geofence API.

Media

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Runtime prerequisites
None
Description

Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.

Alternatives

If you're showing picture-in-picture video, use Picture-in-Picture mode.

Media sedang diproses

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProcessing
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROCESSING
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
Runtime prerequisites
None
Description

Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's mediaProcessing foreground services.)

Your app should manually stop the media processing service in the following scenario:

If the timeout period is reached, the system calls the service's Service.onTimeout(int, int) method. At this time, the service has a few seconds to call Service.stopSelf(). If the service does not call Service.stopSelf(), an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".

Note: Service.onTimeout(int, int) is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.

Proyeksi media

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
mediaProjection
Izin yang akan dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_MEDIA_PROJECTION
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Prasyarat runtime

Panggil metode createScreenCaptureIntent() sebelum memulai layanan latar depan. Dengan melakukannya, notifikasi izin akan ditampilkan kepada pengguna; pengguna harus memberikan izin sebelum Anda dapat membuat layanan.

Setelah membuat layanan latar depan, Anda dapat memanggil MediaProjectionManager.getMediaProjection().

Deskripsi

Proyeksikan konten ke layar non-utama atau perangkat eksternal menggunakan MediaProjection API. Konten ini tidak harus berupa konten media saja.

Alternatif

Untuk melakukan streaming media ke perangkat lain, gunakan Google Cast SDK.

Mikrofon

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di
android:foregroundServiceType
microphone
Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_MICROPHONE
Konstanta untuk diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Prasyarat runtime

Meminta dan diberikan izin runtime RECORD_AUDIO.

Deskripsi

Lanjutkan perekaman mikrofon dari latar belakang, seperti perekam suara atau aplikasi komunikasi.

Panggilan telepon

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
phoneCall
Izin yang akan dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_PHONE_CALL
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Prasyarat runtime

Setidaknya salah satu kondisi berikut harus terpenuhi:

  • Aplikasi adalah aplikasi pemanggil default melalui peran ROLE_DIALER.
Deskripsi

Lanjutkan panggilan yang sedang berlangsung menggunakan ConnectionService API.

Alternatif

Jika Anda perlu melakukan panggilan telepon, video, atau VoIP, sebaiknya gunakan library android.telecom.

Sebaiknya gunakan CallScreeningService untuk menyaring panggilan.

Pengiriman pesan jarak jauh

Foreground service type to declare in manifest under
android:foregroundServiceType
remoteMessaging
Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Runtime prerequisites
None
Description
Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.

Layanan singkat

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
shortService
Izin untuk dideklarasikan dalam manifes
Tidak ada
Konstanta yang akan diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Prasyarat runtime
Tidak ada
Deskripsi

Menyelesaikan pekerjaan penting dengan cepat, yang tidak dapat disela atau ditunda.

Jenis ini memiliki beberapa karakteristik unik:

  • Hanya dapat dijalankan dalam waktu singkat (sekitar 3 menit).
  • Tidak ada dukungan untuk layanan latar depan melekat.
  • Tidak dapat memulai layanan latar depan lainnya.
  • Tidak memerlukan izin khusus jenis, meskipun masih memerlukan izin FOREGROUND_SERVICE.
  • shortService hanya dapat berubah menjadi jenis layanan lain jika aplikasi saat ini memenuhi syarat untuk memulai layanan latar depan baru.
  • Layanan latar depan dapat mengubah jenisnya menjadi shortService kapan saja, dan pada saat itulah periode waktu tunggu dimulai.

Waktu tunggu untuk shortService dimulai sejak Service.startForeground() dipanggil. Aplikasi diharapkan memanggil Service.stopSelf() atau Service.stopForeground() sebelum waktu tunggu habis. Jika tidak, Service.onTimeout() baru akan dipanggil dan memberi aplikasi kesempatan singkat untuk memanggil stopSelf() atau stopForeground() guna menghentikan layanannya.

Tidak lama setelah Service.onTimeout() dipanggil, aplikasi akan memasuki status cache dan tidak lagi dianggap berada di latar depan, kecuali jika pengguna berinteraksi secara aktif dengan aplikasi. Tidak lama setelah aplikasi di-cache dan layanan tidak berhenti, aplikasi akan menerima ANR. Pesan ANR menyebutkan FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Karena alasan ini, mengimplementasikan callback Service.onTimeout() dianggap sebagai praktik terbaik.

Callback Service.onTimeout() tidak ada di Android 13 dan yang lebih rendah. Jika layanan yang sama berjalan di perangkat tersebut, layanan tidak akan mengalami waktu tunggu, begitu juga ANR. Pastikan layanan Anda berhenti begitu selesai memproses tugas, meskipun belum menerima callback Service.onTimeout().

Penting untuk diperhatikan bahwa jika waktu tunggu shortService tidak dipatuhi, aplikasi akan ANR meskipun memiliki layanan latar depan lain yang valid atau proses siklus proses aplikasi lainnya yang berjalan.

Jika aplikasi dapat dilihat oleh pengguna atau memenuhi salah satupengecualian yang memungkinkan layanan latar depan dimulai dari latar belakang, memanggil Service.StartForeground() sekali lagi dengan parameter FOREGROUND_SERVICE_TYPE_SHORT_SERVICE akan memperpanjang waktu tunggu 3 menit lagi. Jika aplikasi tidak terlihat oleh pengguna dan tidak memenuhi salah satu pengecualian, setiap upaya untuk memulai layanan latar depan lainnya, apa pun jenisnya, akan menyebabkan ForegroundServiceStartNotAllowedException.

Jika pengguna menonaktifkan pengoptimalan baterai untuk aplikasi Anda, aplikasi tersebut masih terpengaruh oleh waktu tunggu shortService FGS.

Jika Anda memulai layanan latar depan yang menyertakan jenis shortService dan jenis layanan latar depan lainnya, sistem akan mengabaikan deklarasi jenis shortService. Namun, layanan tetap harus mematuhi prasyarat jenis lain yang dideklarasikan. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi layanan latar depan.

Penggunaan khusus

Foreground service type to declare in manifest under
android:foregroundServiceType
specialUse
Permission to declare in your manifest
FOREGROUND_SERVICE_SPECIAL_USE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Runtime prerequisites
None
Description

Covers any valid foreground service use cases that aren't covered by the other foreground service types.

In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE foreground service type, developers should declare use cases in the manifest. To do so, they specify the <property> element within the <service> element. These values and corresponding use cases are reviewed when you submit your app in the Google Play Console. The use cases you provide are free-form, and you should make sure to provide enough information to let the reviewer see why you need to use the specialUse type.

<service android:name="fooService" android:foregroundServiceType="specialUse">
  <property android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
      android:value="explanation_for_special_use"/>
</service>

Sistem dikecualikan

Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
android:foregroundServiceType
systemExempted
Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Konstanta untuk diteruskan ke startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Prasyarat runtime
Tidak ada
Deskripsi

Ditujukan bagi aplikasi sistem dan integrasi sistem tertentu, untuk terus menggunakan layanan latar depan.

Untuk menggunakan jenis ini, aplikasi harus memenuhi setidaknya salah satu kriteria berikut:

Penegakan kebijakan Google Play untuk menggunakan jenis layanan latar depan

Jika aplikasi menargetkan Android 14 atau yang lebih baru, Anda harus menyatakan jenis layanan latar depan aplikasi di halaman konten aplikasi Konsol Play (Kebijakan > Konten aplikasi). Untuk informasi selengkapnya tentang cara mendeklarasikan jenis layanan latar depan di Konsol Play, lihat Memahami persyaratan layanan latar depan dan intent layar penuh.