Untuk mendorong agar developer berusaha lebih keras menentukan layanan
latar depan yang ditampilkan kepada pengguna, Android 10 memperkenalkan atribut android:foregroundServiceType
dalam elemen <service>
.
Jika menargetkan Android 14, aplikasi Anda harus menentukan jenis layanan latar depan yang sesuai. Seperti pada versi Android sebelumnya, beberapa jenis dapat digabungkan. Daftar ini menunjukkan jenis layanan latar depan yang dapat dipilih:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
Jika kasus penggunaan di aplikasi Anda tidak terkait dengan salah satu jenis ini, sebaiknya migrasikan logika untuk menggunakan WorkManager atau tugas transfer data yang dimulai pengguna
Jenis health, remoteMessaging, shortService, specialUse
, dan systemExempted
masih baru di Android 14.
Cuplikan kode berikut menyediakan contoh deklarasi jenis layanan latar depan dalam manifes:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<application ...>
<service
android:name=".MyMediaPlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="false">
</service>
</application>
</manifest>
Jika aplikasi yang menargetkan Android 14 tidak menentukan jenis untuk layanan tertentu dalam
manifes, sistem akan memunculkan MissingForegroundServiceTypeException
saat memanggil startForeground()
untuk layanan itu.
Mendeklarasikan izin baru untuk menggunakan jenis layanan latar depan
Jika aplikasi yang menargetkan Android 14 menggunakan layanan latar depan, aplikasi tersebut harus mendeklarasikan izin tertentu, berdasarkan jenis layanan latar depan, yang diperkenalkan Android 14. Izin ini muncul di bagian berlabel "izin yang harus Anda deklarasikan dalam file manifes" di bagian kasus penggunaan dan penerapan yang dimaksudkan untuk setiap jenis layanan latar depan di halaman ini.
Semua izin ditentukan sebagai izin normal dan diberikan secara default. Pengguna tidak dapat mencabut izin ini.
Menyertakan jenis layanan latar depan saat runtime
Praktik terbaik untuk aplikasi yang memulai layanan latar depan adalah menggunakan
versi ServiceCompat
startForeground()
(tersedia di androidx-core
1.12 dan yang lebih baru) tempat Anda meneruskan bilangan bulat
dari jenis layanan latar depan bitwise. Anda dapat memilih untuk meneruskan satu atau beberapa nilai
jenis.
Biasanya, Anda hanya boleh mendeklarasikan jenis yang diperlukan untuk kasus penggunaan tertentu. Hal ini memudahkan Anda memenuhi ekspektasi sistem untuk setiap jenis layanan latar depan. Jika layanan latar depan dimulai dengan beberapa jenis, layanan latar depan harus mematuhi persyaratan penerapan platform dari semua jenis.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Jika jenis layanan latar depan tidak ditentukan dalam panggilan, jenis layanan akan ditetapkan secara default
ke nilai yang ditentukan dalam manifes. Jika Anda tidak menentukan jenis
layanan dalam manifes, sistem akan menampilkan
MissingForegroundServiceTypeException
.
Jika layanan latar depan memerlukan izin baru setelah diluncurkan, Anda
harus memanggil startForeground()
lagi dan menambahkan jenis layanan baru. Misalnya, aplikasi kebugaran menjalankan layanan pemantau lari yang selalu memerlukan
informasi location
, tetapi mungkin memerlukan atau tidak memerlukan izin media
. Anda
harus mendeklarasikan location
dan mediaPlayback
dalam manifes. Jika pengguna memulai run dan hanya ingin melacak lokasinya, aplikasi Anda harus memanggil startForeground()
dan meneruskan jenis layanan location
saja. Kemudian, jika pengguna
ingin mulai memutar audio, panggil startForeground()
lagi dan teruskan
location|mediaPlayback
.
Pemeriksaan runtime sistem
Sistem akan memeriksa penggunaan jenis layanan latar depan yang tepat dan mengonfirmasi bahwa
aplikasi telah meminta izin runtime yang tepat atau menggunakan API yang diperlukan.
Misalnya, sistem mengharapkan aplikasi yang menggunakan jenis layanan latar depan
FOREGROUND_SERVICE_TYPE_LOCATION
untuk meminta
ACCESS_COARSE_LOCATION
atau ACCESS_FINE_LOCATION
.
Artinya, aplikasi harus mengikuti urutan operasi
yang sangat spesifik saat meminta izin dari pengguna dan memulai
layanan latar depan. Izin harus diminta dan diberikan sebelum
aplikasi mencoba memanggil startForeground()
. Aplikasi yang meminta izin
yang sesuai setelah layanan latar depan dimulai harus mengubah urutan
operasi ini dan meminta izin sebelum memulai layanan latar depan.
Detail penerapan platform akan muncul di bagian berlabel "persyaratan runtime" di bagian kasus penggunaan dan penerapan yang diinginkan untuk setiap jenis layanan latar depan di halaman ini.
Kasus penggunaan dan penerapan yang ditargetkan untuk setiap jenis layanan latar depan
Untuk menggunakan jenis layanan latar depan tertentu, Anda harus mendeklarasikan izin tertentu dalam file manifes, Anda harus memenuhi persyaratan runtime tertentu, dan aplikasi Anda harus memenuhi salah satu dari kumpulan kasus penggunaan yang dimaksudkan untuk jenis tersebut. Bagian berikut menjelaskan izin yang harus Anda deklarasikan, prasyarat runtime, dan kasus penggunaan yang dimaksudkan untuk setiap jenis.
Kamera
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bagian
android:foregroundServiceType
camera
- Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_CAMERA
- Konstanta untuk 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 depancamera
saat aplikasi berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan 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 untuk dinyatakan dalam manifes di bawah
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 selengkapnya.
Kesehatan
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
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 diberi setidaknya salah satu izin runtime berikut:
Catatan: Izin runtime
BODY_SENSORS
tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depanhealth
yang menggunakan sensor tubuh saat aplikasi berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan memulai layanan latar depan yang memerlukan izin saat digunakan.- Deskripsi
Semua kasus penggunaan yang berjalan lama untuk mendukung aplikasi dalam kategori kebugaran seperti pelacak latihan.
Lokasi
- Jenis layanan latar depan yang akan dinyatakan dalam manifes di
android:foregroundServiceType
location
- Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_LOCATION
- Konstanta untuk diteruskan ke
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Prasyarat runtime
Pengguna harus mengaktifkan layanan lokasi dan aplikasi harus diberi setidaknya salah satu izin runtime berikut:
Catatan: Untuk memeriksa apakah pengguna telah mengaktifkan layanan lokasi serta memberikan akses ke izin runtime, gunakan
PermissionChecker#checkSelfPermission()
Catatan: Izin runtime lokasi tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan
location
saat aplikasi berada di latar belakang, kecuali jika Anda telah diberi izin runtimeACCESS_BACKGROUND_LOCATION
. Untuk informasi selengkapnya, lihat Pembatasan untuk memulai layanan latar depan yang memerlukan izin saat digunakan.- 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, sebaiknya gunakan API pembatasan wilayah.
Media
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
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 fungsi Perekaman Video Digital (DVR) di Android TV.
- Alternatif
- Jika Anda menampilkan video picture-in-picture, gunakan mode Picture-in-Picture.
Proyeksi media
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
android:foregroundServiceType
mediaProjection
- Izin untuk dideklarasikan dalam manifes Anda
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 dapat membuat layanan.Setelah membuat layanan latar depan, Anda dapat memanggil
MediaProjectionManager.getMediaProjection()
.- Deskripsi
Memproyeksikan 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 SDK Google Cast.
Mikrofon
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
android:foregroundServiceType
microphone
- Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_MICROPHONE
- Konstanta untuk diteruskan ke
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Prasyarat runtime
Minta dan diberi izin runtime
RECORD_AUDIO
.Catatan: Izin runtime
RECORD_AUDIO
tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depanmicrophone
saat aplikasi berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan memulai layanan latar depan yang memerlukan izin saat digunakan.- Deskripsi
Melanjutkan perekaman mikrofon dari latar belakang, seperti perekam suara atau aplikasi komunikasi.
Panggilan telepon
- Jenis layanan latar depan untuk dinyatakan dalam manifes di bawah
android:foregroundServiceType
phoneCall
- Izin untuk dideklarasikan dalam manifes Anda
FOREGROUND_SERVICE_PHONE_CALL
- Konstanta untuk diteruskan ke
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Prasyarat runtime
Setidaknya salah satu syarat berikut harus terpenuhi:
- Aplikasi telah mendeklarasikan izin
MANAGE_OWN_CALLS
dalam file manifesnya.
- Aplikasi telah mendeklarasikan izin
- Aplikasi adalah aplikasi telepon default melalui
peran
ROLE_DIALER
.
- Aplikasi adalah aplikasi telepon default melalui
peran
- 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 memanggilService.stopSelf()
atauService.stopForeground()
sebelum waktu tunggu habis. Jika tidak,Service.onTimeout()
baru akan dipanggil dan memberi aplikasi kesempatan singkat untuk memanggilstopSelf()
ataustopForeground()
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 menyebutkanFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. Karena alasan ini, mengimplementasikan callbackService.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 callbackService.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 parameterFOREGROUND_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 menyebabkanForegroundServiceStartNotAllowedException
.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 jenisshortService
. 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 menggunakanspecialUse
.<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 yang akan dinyatakan dalam manifes di
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
SCHEDULE_EXACT_ALARM
atauUSE_EXACT_ALARM
dan menggunakan Layanan Latar Depan untuk melanjutkan alarm di latar belakang, termasuk alarm khusus haptic. 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 mengetahui informasi selengkapnya tentang cara mendeklarasikan jenis layanan latar depan di Konsol Play, lihat Memahami layanan latar depan dan persyaratan intent layar penuh.