Halaman ini diterjemahkan oleh Cloud Translation API.

Jenis layanan latar depan

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

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

Catatan: Izin runtime CAMERA tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan camera saat aplikasi berada di latar belakang dan Anda tidak dapat meluncurkan layanan latar depan camera dari penerima BOOT_COMPLETED, dengan beberapa pengecualian. Untuk mengetahui informasi selengkapnya, lihat Batasan untuk memulai layanan latar depan yang memerlukan izin saat digunakan.
Deskripsi: Terus mengakses kamera dari latar belakang, seperti aplikasi video chat yang memungkinkan 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:
Minta dan diberi setidaknya salah satu izin runtime berikut:
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

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian

android:foregroundServiceType

dataSync

Izin yang akan dideklarasikan dalam manifes

FOREGROUND_SERVICE_DATA_SYNC

Konstanta yang akan 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 di bagian

android:foregroundServiceType

health

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_HEALTH

Konstanta untuk 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

Foreground service type to declare in manifest under

android:foregroundServiceType

location

Permission to declare in your manifest

FOREGROUND_SERVICE_LOCATION

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_LOCATION

Runtime prerequisites

The user must have enabled location services and the app must be granted at least one of the following runtime permissions:

Description

Long-running use cases that require location access, such as navigation and location sharing.

Alternatives

If your app needs to be triggered when the user reaches specific locations, consider using the geofence API instead.

Media

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType: mediaPlayback
Izin yang akan dideklarasikan dalam manifes: FOREGROUND_SERVICE_MEDIA_PLAYBACK
Konstanta yang akan diteruskan ke startForeground(): FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Prasyarat runtime: Tidak ada
Deskripsi: Melanjutkan pemutaran audio atau video dari latar belakang. Mendukung fungsi Perekaman Video Digital (DVR) di Android TV.

Catatan: Aplikasi yang menargetkan Android 15 atau yang lebih tinggi tidak diizinkan untuk meluncurkan layanan latar depan pemutaran media dari penerima siaran BOOT_COMPLETED. Untuk mengetahui informasi selengkapnya, lihat Pembatasan pada penerima siaran BOOT_COMPLETED yang meluncurkan layanan latar depan.
Alternatif: Jika Anda menampilkan video picture-in-picture, gunakan mode Picture-in-Picture.

Media sedang diproses

Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah

android:foregroundServiceType

mediaProcessing

Izin untuk dideklarasikan dalam manifes Anda

FOREGROUND_SERVICE_MEDIA_PROCESSING

Konstanta untuk diteruskan ke startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Prasyarat runtime

Tidak ada

Deskripsi

Layanan untuk melakukan operasi yang memakan waktu pada aset media, seperti mengonversi media ke format yang berbeda. Sistem ini mengizinkan layanan ini berjalan dalam waktu terbatas; dalam keadaan normal, batas waktu ini adalah 6 jam dari setiap 24 jam. (Batas ini digunakan bersama oleh semua layanan latar depan mediaProcessing aplikasi.)

Aplikasi Anda harus menghentikan layanan pemrosesan media secara manual dalam skenario berikut:

Saat operasi transcoding selesai atau mencapai status kegagalan, minta layanan memanggil Service.stopForeground() dan Service.stopSelf() untuk menghentikan layanan sepenuhnya.

Jika periode waktu tunggu tercapai, sistem akan memanggil metode Service.onTimeout(int, int) layanan. Pada saat ini, layanan memiliki beberapa detik untuk memanggil Service.stopSelf(). Jika layanan tidak memanggil Service.stopSelf(), ANR akan terjadi dengan pesan error ini: "Layanan latar depan <fgs_type> tidak berhenti dalam waktu tunggunya: <component_name>".

Catatan: Service.onTimeout(int, int) tidak tersedia di Android 14 atau yang lebih rendah. Pada perangkat yang menjalankan versi tersebut, jika layanan pemrosesan media mencapai periode waktu tunggu, sistem akan langsung meng-cache aplikasi. Karena alasan ini, aplikasi Anda tidak boleh menunggu untuk mendapatkan notifikasi waktu tunggu. Sebagai gantinya, aplikasi harus menghentikan layanan latar depan atau mengubahnya ke layanan latar belakang sesegera mungkin.

Proyeksi media

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType: mediaProjection
Izin yang akan dideklarasikan dalam manifes: 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. Tindakan ini akan menampilkan notifikasi izin 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.

Catatan: Aplikasi yang menargetkan Android 15 atau yang lebih tinggi tidak diizinkan untuk meluncurkan layanan latar depan proyeksi media dari penerima siaran BOOT_COMPLETED. Untuk mengetahui informasi selengkapnya, lihat Pembatasan pada penerima siaran BOOT_COMPLETED yang meluncurkan layanan latar depan.
Alternatif: Untuk melakukan streaming media ke perangkat lain, gunakan Google Cast SDK.

Mikrofon

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType: microphone
Izin yang akan dideklarasikan dalam manifes: FOREGROUND_SERVICE_MICROPHONE
Konstanta yang akan diteruskan ke startForeground(): FOREGROUND_SERVICE_TYPE_MICROPHONE
Prasyarat runtime: Minta dan dapatkan izin runtime RECORD_AUDIO.

Catatan: Izin runtime RECORD_AUDIO tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan microphone saat aplikasi berada di latar belakang dan Anda tidak dapat meluncurkan layanan latar depan microphone dari penerima BOOT_COMPLETED, dengan beberapa pengecualian. Untuk mengetahui informasi selengkapnya, lihat Batasan untuk memulai layanan latar depan yang memerlukan izin saat digunakan.
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

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

Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah

android:foregroundServiceType

shortService

Izin untuk dideklarasikan dalam manifes Anda

Tidak ada

Konstanta untuk 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 ke 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 itu periode waktu tunggu akan 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 dari jenis lain yang dideklarasikan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Layanan latar depan.

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.