Jenis layanan latar depan wajib diisi

To help developers be more intentional with defining user-facing foreground services, Android 10 introduced the android:foregroundServiceType attribute within the <service> element.

If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:

If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.

The health, remoteMessaging, shortService, specialUse, and systemExempted types are new in Android 14.

The following code snippet provides an example of a foreground service type declaration in the manifest:

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

If an app that targets Android 14 doesn't define types for a given service in the manifest, then the system will raise MissingForegroundServiceTypeException upon calling startForeground() for that service.

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 dari startForeground() (tersedia di androidx-core 1.12 dan yang lebih tinggi) 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 yang digunakan dalam manifes akan ditetapkan secara default. 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 pelacak lari yang selalu memerlukan informasi location, tetapi mungkin atau mungkin tidak memerlukan izin media. Anda harus mendeklarasikan location dan mediaPlayback dalam manifes. Jika pengguna mulai berlari dan hanya ingin lokasi mereka dilacak, 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

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.

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

In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.

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

Note: The CAMERA runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a camera foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

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

Perangkat yang terhubung

Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Runtime prerequisites

At least one of the following conditions must be true:

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

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

Jenis layanan latar depan yang akan dideklarasikan dalam manifes di bagian
android:foregroundServiceType
shortService
Izin untuk dideklarasikan dalam manifes
Tidak ada
Konstanta yang akan 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 menjadi 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 itulah periode waktu tunggu 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 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 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

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.