Jenis layanan latar depan wajib diisi

为了帮助开发者更有目的地定义面向用户的前台服务，Android 10 在 <service> 元素内引入了 android:foregroundServiceType 属性。

如果您的应用以 Android 14 为目标平台，则必须指定适当的前台服务类型。与以前的 Android 版本一样，可组合使用多个类型。下面列出了可供选择的前台服务类型：

• camera
• connectedDevice
• dataSync
• health
• location
• mediaPlayback
• mediaProjection
• microphone
• phoneCall
• remoteMessaging
• shortService
• specialUse
• systemExempted

如果应用中的用例与这些类型均不相关，强烈建议您迁移逻辑以使用 WorkManager 或用户发起的数据传输作业。

Android 14 中新增了 health, remoteMessaging, shortService, specialUse 和 systemExempted 类型。

以下代码段提供了一个清单中的前台服务类型声明示例：

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

如果以 Android 14 为目标平台的应用未在清单中定义给定服务的类型，系统会在调用 startForeground() 时引发 MissingForegroundServiceTypeException。

Mendeklarasikan izin baru untuk menggunakan jenis layanan latar depan

If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.

All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.

Caution: If you call startForeground() without declaring the appropriate foreground service type permission, the system throws a SecurityException.

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

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

Caution: If your app doesn't fulfill all of the runtime requirements for starting a foreground service, the system throws a SecurityException after you call startForeground() for that service. This prevents the foreground service from starting, might cause a running foreground service to be removed from the foreground process state, and might cause your app to crash.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

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 dideklarasikan 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 depan camera saat aplikasi Anda berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan memulai layanan latar depan yang memerlukan izin saat digunakan.

Deskripsi

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

Perangkat yang terhubung

Jenis layanan latar depan untuk dideklarasikan dalam manifes di

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 berikan minimal 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.

Catatan: Jika aplikasi Anda melakukan proyeksi atau operasi pesan jarak jauh, gunakan jenis proyeksi media atau pesan jarak jauh yang sesuai.

Alternatif

Jika aplikasi Anda perlu melakukan transfer data berkelanjutan 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, sebaiknya gunakan Bluetooth Scan API.

Sinkronisasi data

Jenis layanan latar depan untuk 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

Buat tugas transfer data yang dimulai pengguna untuk memungkinkan pengguna memulai tugas upload atau download data yang berjalan lama.

Gunakan API pengelola download untuk mendownload data dari URI.

Gunakan BackupManager untuk mencadangkan atau memulihkan data.

Untuk kasus penggunaan lainnya, pertimbangkan WorkManager.

Catatan: Pada versi Android mendatang, jenis layanan latar depan ini tidak akan digunakan lagi. Sebaiknya Anda bermigrasi ke salah satu alternatif yang tercantum.

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:

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

Catatan: Izin runtime BODY_SENSORS tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan health 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 untuk dideklarasikan 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

Minta dan berikan minimal salah satu izin runtime berikut:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

Catatan: Izin runtime lokasi tunduk pada pembatasan saat digunakan. Karena alasan ini, Anda tidak dapat membuat layanan latar depan location saat aplikasi Anda berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan 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 dideklarasikan 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 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 dideklarasikan dalam manifes di

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

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

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 depan microphone saat aplikasi Anda berada di latar belakang, dengan beberapa pengecualian. Untuk informasi selengkapnya, lihat Pembatasan 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 untuk dideklarasikan dalam manifes di

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 adalah aplikasi telepon 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

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

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. Kasus penggunaan yang Anda berikan adalah bentuk bebas, dan Anda harus memastikan untuk memberikan informasi yang cukup agar peninjau memahami alasan Anda perlu menggunakan jenis 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 mengetahui informasi selengkapnya tentang cara mendeklarasikan jenis layanan latar depan di Konsol Play, lihat Memahami layanan latar depan dan persyaratan intent layar penuh.