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

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.

Perhatian: Jika Anda memanggil startForeground() tanpa mendeklarasikan izin jenis layanan latar depan yang sesuai, sistem akan menampilkan SecurityException.

Menyertakan jenis layanan latar depan saat runtime

对于启动前台服务的应用，最佳实践是使用 startForeground() 的 ServiceCompat 版本（在 androidx-core 1.12 及更高版本中提供），并在其中传入前台服务类型的按位整数。您可以选择传递一个或多个类型值。

通常，您应仅声明特定用例所需的类型。这样可以更轻松地满足系统对每种前台服务类型的预期。如果某项前台服务以多种类型启动，则该前台服务必须遵守所有类型的平台强制执行要求。

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

如果在调用中未指定前台服务类型，则类型默认为清单中定义的值。如果您未在清单中指定服务类型，系统会抛出 MissingForegroundServiceTypeException。

如果前台服务在启动后需要新权限，您应再次调用 startForeground() 并添加新的服务类型。例如，假设一款健身应用运行一项始终需要 location 信息但可能不需要 media 权限的跑步跟踪器服务。您需要在清单中同时声明 location 和 mediaPlayback。如果用户开始跑步，只希望跟踪其位置信息，您的应用应调用 startForeground()，并仅传递 location 服务类型。然后，如果用户想开始播放音频，请再次调用 startForeground() 并传递 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.

Perhatian: Jika aplikasi Anda tidak memenuhi semua persyaratan runtime untuk memulai layanan latar depan, sistem akan menampilkan SecurityException setelah Anda memanggil startForeground() untuk layanan tersebut. Hal ini mencegah layanan latar depan dimulai, dapat menyebabkan layanan latar depan yang berjalan dihapus dari status proses latar depan, dan dapat menyebabkan aplikasi Anda error.

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:

• Deklarasikan minimal satu izin berikut dalam manifes:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Minta dan dapatkan setidaknya 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 operasi pesan jarak jauh atau proyeksi, gunakan jenis proyeksi media atau pesan jarak jauh yang sesuai.

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

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

health

在清单中声明的权限

FOREGROUND_SERVICE_HEALTH

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_HEALTH

运行时前提条件

必须至少满足以下其中一个条件：

• 在清单中声明 HIGH_SAMPLING_RATE_SENSORS 权限。

• 至少请求并被授予以下其中一项运行时权限：

  • 在 API 级别 35 及更低级别上使用 BODY_SENSORS
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

注意：BODY_SENSORS 和基于传感器的读取运行时权限受“在使用时”限制。因此，除非您已获得 BODY_SENSORS_BACKGROUND（API 级别 33 到 35）或 READ_HEALTH_DATA_IN_BACKGROUND（API 级别 36 及更高级别）权限，否则您无法创建在应用处于后台运行时使用身体传感器的 health 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

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:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

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

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

systemExempted

在清单中声明的权限

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

运行时前提条件

无

说明

为系统应用和特定系统集成预留，使其能继续使用前台服务。

如需使用此类型，应用必须至少满足以下条件之一：

• 设备处于演示模式状态
• 应用是设备所有者
• 应用是性能分析器所有者
• 属于具有 ROLE_EMERGENCY 角色的安全应用
• 属于设备管理应用
• 具有 SCHEDULE_EXACT_ALARM 或 USE_EXACT_ALARM 权限且使用前台服务在后台继续闹钟（包括仅振动闹钟）的应用。

• VPN 应用（使用设置 > 网络和互联网 > VPN 进行配置）

  否则，声明此类型会导致系统抛出 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.