Jenis layanan latar depan

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mulai Android 14 (API level 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

Foreground service type to declare in manifest under android:foregroundServiceType

camera

Permission to declare in your manifest

FOREGROUND_SERVICE_CAMERA

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_CAMERA

Runtime prerequisites

Request and be granted the CAMERA runtime permission

Description

Continue to access the camera from the background, such as video chat apps that allow for multitasking.

Perangkat yang terhubung

Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah

android:foregroundServiceType

connectedDevice

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_CONNECTED_DEVICE

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Prasyarat runtime

Setidaknya salah satu syarat berikut harus terpenuhi:

• Deklarasikan minimal satu izin berikut dalam manifes:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Minta dan diberi setidaknya salah satu izin runtime berikut:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Panggil UsbManager.requestPermission()

Deskripsi

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

Alternatif

Jika aplikasi Anda perlu melakukan transfer data secara terus-menerus ke perangkat eksternal, sebaiknya gunakan 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, pertimbangkan untuk menggunakan Bluetooth Scan API.

Sinkronisasi data

Foreground service type to declare in manifest under

android:foregroundServiceType

dataSync

Permission to declare in your manifest

FOREGROUND_SERVICE_DATA_SYNC

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Runtime prerequisites

None

Description

Data transfer operations, such as the following:

• Data upload or download
• Backup-and-restore operations
• Import or export operations
• Fetch data
• Local file processing
• Transfer data between a device and the cloud over a network

Alternatives

See Alternatives to data sync foreground services for detailed information.

Kesehatan

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian

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:

• Deklarasikan izin HIGH_SAMPLING_RATE_SENSORS di manifes Anda.

• Minta dan dapatkan setidaknya salah satu izin runtime berikut:

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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

Jenis layanan latar depan yang akan dinyatakan dalam manifes di

android:foregroundServiceType

mediaPlayback

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_MEDIA_PLAYBACK

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

Prasyarat runtime

Tidak ada

Deskripsi

Melanjutkan pemutaran audio atau video dari latar belakang. Mendukung Video Digital Fungsi perekaman (DVR) di Android TV.

Alternatif

Jika Anda menampilkan video picture-in-picture, gunakan Mode Picture-in-Picture.

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:

• When the transcoding operation finishes or reaches a failure state, have the service call Service.stopForeground() and Service.stopSelf() to stop the service completely.

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 dinyatakan dalam manifes di

android:foregroundServiceType

mediaProjection

Izin yang akan dideklarasikan dalam manifes

FOREGROUND_SERVICE_MEDIA_PROJECTION

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Prasyarat runtime

Panggil metode createScreenCaptureIntent() sebelum memulai layanan latar depan. Tindakan ini akan menampilkan notifikasi izin kepada pengguna; pengguna harus memberikan izin sebelum Anda bisa 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

Foreground service type to declare in manifest under

android:foregroundServiceType

microphone

Permission to declare in your manifest

FOREGROUND_SERVICE_MICROPHONE

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MICROPHONE

Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

Panggilan telepon

Jenis layanan latar depan yang akan dinyatakan dalam manifes di

android:foregroundServiceType

phoneCall

Izin untuk 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 telah mendeklarasikan izin MANAGE_OWN_CALLS dalam file manifesnya.

• Aplikasi ini 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, pertimbangkan untuk menggunakan library android.telecom.

Sebaiknya gunakan CallScreeningService untuk menyaring panggilan.

Pengiriman pesan jarak jauh

Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah

android:foregroundServiceType

remoteMessaging

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_REMOTE_MESSAGING

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

Prasyarat runtime

Tidak ada

Deskripsi

Mentransfer pesan teks dari satu perangkat ke perangkat lainnya. Membantu kontinuitas tugas fitur pesan pengguna saat mereka beralih perangkat.

Layanan singkat

Foreground service type to declare in manifest under

android:foregroundServiceType

shortService

Permission to declare in your manifest

None

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Runtime prerequisites

None

Description

Quickly finish critical work that cannot be interrupted or postponed.

This type has some unique characteristics:

• Can only run for a short period of time (about 3 minutes).
• No support for sticky foreground services.
• Cannot start other foreground services.
• Doesn't require a type-specific permission, though it still requires the FOREGROUND_SERVICE permission.
• A shortService can only change to another service type if the app is currently eligible to start a new foreground service.
• A foreground service can change its type to shortService at any time, at which point the timeout period begins.

The timeout for shortService begins from the moment that Service.startForeground() is called. The app is expected to call Service.stopSelf() or Service.stopForeground() before the timeout occurs. Otherwise, the new Service.onTimeout() is called, giving apps a brief opportunity to call stopSelf() or stopForeground() to stop their service.

A short time after Service.onTimeout() is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentions FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these reasons, it's considered best practice to implement the Service.onTimeout() callback.

The Service.onTimeout() callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received the Service.onTimeout() callback yet.

It's important to note that if the timeout of the shortService is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.

If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling Service.StartForeground() again with the FOREGROUND_SERVICE_TYPE_SHORT_SERVICE parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes a ForegroundServiceStartNotAllowedException.

If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.

If you start a foreground service that includes the shortService type and another foreground service type, the system ignores the shortService type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.

Penggunaan khusus

Jenis layanan latar depan yang akan dinyatakan dalam manifes di

android:foregroundServiceType

specialUse

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_SPECIAL_USE

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

Prasyarat runtime

Tidak ada

Deskripsi

Mencakup semua kasus penggunaan layanan latar depan yang valid dan tidak tercakup dalam jenis layanan latar depan lainnya.

Selain mendeklarasikan jenis layanan latar depan FOREGROUND_SERVICE_TYPE_SPECIAL_USE, developer juga harus mendeklarasikan kasus penggunaan dalam manifes. Untuk melakukannya, mereka menentukan elemen <property> dalam elemen <service>. Nilai ini dan kasus penggunaan yang sesuai akan ditinjau saat Anda mengirimkan aplikasi di Konsol Google Play. Penggunaan kasus yang Anda berikan menggunakan format bebas, dan Anda harus memastikan agar peninjau dapat mengetahui alasan Anda perlu menggunakan specialUse .

<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:

• Perangkat dalam status mode demo
• Aplikasi adalah Pemilik Perangkat
• Aplikasi adalah Pemilik Profiler
• Aplikasi Keselamatan yang memiliki peran ROLE_EMERGENCY
• Aplikasi Admin Perangkat
• Aplikasi yang memiliki izin SCHEDULE_EXACT_ALARM atau USE_EXACT_ALARM

• Aplikasi VPN (dikonfigurasi menggunakan Setelan > Jaringan & Internet > VPN)

  Jika tidak, mendeklarasikan jenis ini akan menyebabkan sistem menampilkan ForegroundServiceTypeNotAllowedException.

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.