Jenis layanan latar depan

Mulai Android 14 (level API 34), Anda harus mendeklarasikan jenis layanan yang sesuai untuk setiap layanan latar depan. Artinya, Anda harus mendeklarasikan jenis layanan dalam manifes aplikasi, dan juga meminta izin layanan latar depan yang sesuai untuk jenis tersebut (selain meminta izin FOREGROUND_SERVICE). Selain itu, bergantung pada jenis layanan latar depan, Anda mungkin harus meminta izin runtime sebelum meluncurkan layanan.

Kamera

要在清单中的 android:foregroundServiceType 下声明的前台服务类型
camera
要在清单中声明的权限
FOREGROUND_SERVICE_CAMERA
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_CAMERA
运行时前提条件

请求并获得 CAMERA 运行时权限

说明

继续在后台访问相机，例如支持多任务的视频聊天应用。

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

在清单中声明的前台服务类型
android:foregroundServiceType
dataSync
要在清单中声明的权限
FOREGROUND_SERVICE_DATA_SYNC
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_DATA_SYNC
运行时前提条件
无
说明

数据传输操作，例如：

  • 数据上传或下载
  • 备份和恢复操作
  • 导入或导出操作
  • 获取数据
  • 本地文件处理
  • 通过网络在设备和云端之间传输数据
替代方案

如需了解详情，请参阅数据同步前台服务的替代方案。

Kesehatan

Jenis layanan latar depan yang akan dideklarasikan dalam manifes
android:foregroundServiceType
health
Izin yang akan 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:

Deskripsi

Semua kasus penggunaan yang berjalan lama untuk mendukung aplikasi dalam kategori kebugaran seperti pelacak latihan.

Lokasi

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
location
在清单中声明的权限
FOREGROUND_SERVICE_LOCATION
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_LOCATION
运行时前提条件

用户必须已启用位置信息服务，并且应用必须至少获得以下一项运行时权限：

说明

需要位置信息使用权的长时间运行的用例，例如导航和位置信息分享。

替代方案

如果您的应用需要在用户到达特定位置时触发，请考虑改用 Geofence API。

Media

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

Media sedang diproses

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
mediaProcessing
在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
运行时前提条件
无
说明

用于对媒体资源执行耗时的操作（例如将媒体转换为其他格式）的服务。系统允许此服务运行的时间有限；在正常情况下，此时限为每天 24 小时中的 6 小时。（此限制由应用的所有 mediaProcessing 前台服务共享。）

在以下情况下，您的应用应手动停止媒体处理服务：

如果超时期限已到，系统会调用服务的 Service.onTimeout(int, int) 方法。此时，该服务有几秒钟的时间来调用 Service.stopSelf()。如果服务未调用 Service.stopSelf()，则会发生 ANR，并显示以下错误消息：“<fgs_type> 的前台服务未在超时时间内停止：<component_name>”。

注意：Service.onTimeout(int, int) 不适用于 Android 14 或更低版本。在搭载这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。相反，它应在适当情况下尽快终止前台服务或将其更改为后台服务。

Proyeksi media

在清单中声明的前台服务类型
android:foregroundServiceType
mediaProjection
要在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
运行时前提条件

在启动前台服务之前，调用 createScreenCaptureIntent() 方法。这样做会向用户显示权限通知；用户必须先授予权限，然后您才能创建服务。

创建前台服务后，您可以调用 MediaProjectionManager.getMediaProjection()。

说明

使用 MediaProjection API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。

替代方案

如需将媒体内容流式传输到其他设备，请使用 Google Cast SDK。

Mikrofon

在清单中声明的前台服务类型
android:foregroundServiceType
microphone
要在清单中声明的权限
FOREGROUND_SERVICE_MICROPHONE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MICROPHONE
运行时前提条件

请求并获得 RECORD_AUDIO 运行时权限。

说明

在后台继续捕获麦克风内容，例如录音器或通信应用。

Panggilan telepon

在清单中声明的前台服务类型
android:foregroundServiceType
phoneCall
要在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_PHONE_CALL
运行时前提条件

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

  • 应用通过 ROLE_DIALER 角色成为默认拨号器应用。
说明

使用 ConnectionService API 继续当前通话。

替代方案

如果您需要拨打电话、进行视频通话或 VoIP 通话，请考虑使用 android.telecom 库。

考虑使用 CallScreeningService 过滤来电。

Pengiriman pesan jarak jauh

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
remoteMessaging
在清单中声明的权限
FOREGROUND_SERVICE_REMOTE_MESSAGING
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
运行时前提条件
无
说明
将短信从一台设备转移到另一台设备。在用户切换设备时，帮助确保用户消息任务的连续性。

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

要在清单中声明的前台服务类型
android:foregroundServiceType
specialUse
在清单中声明的权限
FOREGROUND_SERVICE_SPECIAL_USE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
运行时前提条件
无
说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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
运行时前提条件
无
说明

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

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

Penegakan kebijakan Google Play untuk menggunakan jenis layanan latar depan

如果您的应用以 Android 14 或更高版本为目标平台，您需要在 Play 管理中心的“应用内容”页面（政策 > 应用内容）中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型，请参阅了解前台服务和全屏 intent 要求。