Jenis layanan latar depan wajib diisi

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:

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

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass 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 yang akan dideklarasikan dalam manifes di bagian android:foregroundServiceType
camera
Izin untuk 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, 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 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 bagian
android:foregroundServiceType
dataSync
Izin untuk 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
android:foregroundServiceType
health
Izin untuk 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:

Catatan: Izin runtime BACA berbasis sensor dan BODY_SENSORS tunduk pada batasan saat penggunaan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan health yang menggunakan sensor tubuh saat aplikasi berada di latar belakang, kecuali jika Anda telah diberi izin BODY_SENSORS_BACKGROUND (API level 33 hingga 35) atau READ_HEALTH_DATA_IN_BACKGROUND (API level 36 dan yang lebih tinggi). Untuk informasi selengkapnya, lihat Batasan untuk 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 dideklarasikan dalam manifes di bagian
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:

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. Oleh karena itu, Anda tidak dapat membuat layanan latar depan location saat aplikasi berada di latar belakang, kecuali jika Anda telah diberi izin runtime ACCESS_BACKGROUND_LOCATION. Untuk mengetahui informasi selengkapnya, lihat Batasan 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, pertimbangkan untuk menggunakan geofence API.

Media

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
mediaPlayback
Izin untuk 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.
Alternatif
Jika Anda menampilkan video picture-in-picture, gunakan mode Picture-in-Picture.

Proyeksi media

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

Alternatif

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

Mikrofon

Jenis layanan latar depan yang akan dideklarasikan dalam manifes
android:foregroundServiceType
microphone
Izin untuk 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. Oleh karena itu, Anda tidak dapat membuat layanan latar depan microphone saat aplikasi berada di latar belakang, 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 untuk 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 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 yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
remoteMessaging
Izin untuk dideklarasikan dalam manifes
FOREGROUND_SERVICE_REMOTE_MESSAGING
Konstanta yang akan 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 yang akan dideklarasikan dalam manifes
FOREGROUND_SERVICE_SPECIAL_USE
Konstanta yang akan 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 yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
systemExempted
Izin untuk dideklarasikan dalam manifes
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Konstanta yang akan 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 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 informasi selengkapnya tentang cara mendeklarasikan jenis layanan latar depan di Konsol Play, lihat Memahami persyaratan layanan latar depan dan intent layar penuh.