Począwszy od Androida 14 (interfejs API 34) musisz zadeklarować odpowiedni typ usługi dla każdej usługi na pierwszym planie. Oznacza to, że musisz zadeklarować typ usługi w pliku manifestu aplikacji i poprosić o odpowiednie uprawnienie usługi na pierwszym planie dla tego typu (oprócz uprawnienia FOREGROUND_SERVICE
). Ponadto w zależności od typu usługi na pierwszym planie przed jej uruchomieniem może być konieczne poproszenie o uprawnienia dotyczące czasu wykonywania.
Aparat
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
camera
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_CAMERA
- Stała wartość przekazywana do funkcji
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Wymagania wstępne środowiska wykonawczego
Poproś o uprawnienia czasu działania
CAMERA
i uzyskaj je. .
- Opis
Dalsze korzystanie w tle z aparatu, np. w przypadku aplikacji do obsługi czatu wideo, które umożliwiają wielozadaniowość.
Połączone urządzenie
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
connectedDevice
- 在清单中声明的权限
FOREGROUND_SERVICE_CONNECTED_DEVICE
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中至少声明以下其中一项权限:
请求并获得以下至少一项运行时权限:
- 说明
与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。
- 替代方案
如果您的应用需要持续将数据传输到外部设备,请考虑改用配套设备管理器。使用配套设备在线状态 API 帮助您的应用在配套设备在范围内时保持运行。
如果您的应用需要扫描蓝牙设备,请考虑改用 Bluetooth Scanner API。
Synchronizowanie danych
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
dataSync
- 在清单中声明的权限
FOREGROUND_SERVICE_DATA_SYNC
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_DATA_SYNC
- 运行时前提条件
- 无
- 说明
数据传输操作,例如:
- 数据上传或下载
- 备份和恢复操作
- 导入或导出操作
- 获取数据
- 本地文件处理
- 通过网络在设备和云端之间传输数据
- 替代方案
如需了解详情,请参阅数据同步前台服务的替代方案。
Stan
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
health
- 在清单中声明的权限
FOREGROUND_SERVICE_HEALTH
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_HEALTH
- 运行时前提条件
必须至少满足以下其中一个条件:
在清单中声明
HIGH_SAMPLING_RATE_SENSORS
权限。至少请求并被授予以下其中一项运行时权限:
- 说明
为健身类别的应用(例如锻炼追踪器)提供支持的所有长时间运行的用例。
Lokalizacja
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
location
- 在清单中声明的权限
FOREGROUND_SERVICE_LOCATION
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_LOCATION
- 运行时前提条件
用户必须已启用位置信息服务,并且应用必须至少获得以下一项运行时权限:
- 说明
需要位置信息使用权的长时间运行的用例,例如导航和位置信息分享。
- 替代方案
如果您的应用需要在用户到达特定位置时触发,请考虑改用 Geofence API。
Multimedia
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
mediaPlayback
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Stała wartość przekazywana do funkcji
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Dotyczy to ciągłego odtwarzania dźwięku lub wideo w tle. Obsługa funkcji cyfrowego nagrywania wideo (DVR) na Androidzie TV.
- Alternatywy
Jeśli wyświetlasz film w trybie obrazu w obrazie, użyj trybu obrazu w obrazie.
Przetwarzane materiały
- Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProcessing
- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROCESSING
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
- Runtime prerequisites
- None
- Description
Service for performing time-consuming operations on media assets, like converting media to different formats. The system allows this service a limited time to run; under normal circumstances, this time limit would be 6 hours out of every 24. (This limit is shared by all of an app's
mediaProcessing
foreground services.)Your app should manually stop the media processing service in the following scenario:
- When the transcoding operation finishes or reaches a failure state, have the
service call
Service.stopForeground()
andService.stopSelf()
to stop the service completely.
- When the transcoding operation finishes or reaches a failure state, have the
service call
If the timeout period is reached, the system calls the service's
Service.onTimeout(int, int)
method. At this time, the service has a few seconds to callService.stopSelf()
. If the service does not callService.stopSelf()
, an ANR will occur with this error message: "A foreground service of <fgs_type> did not stop within its timeout: <component_name>".Note:
Service.onTimeout(int, int)
is not available on Android 14 or lower. On devices running those versions, if a media processing service reaches the timeout period, the system immediately caches the app. For this reason, your app shouldn't wait to get a timeout notification. Instead, it should terminate the foreground service or change it to a background service as soon as appropriate.
Wyświetlanie multimediów
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
mediaProjection
- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROJECTION
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- 运行时前提条件
在启动前台服务之前调用
createScreenCaptureIntent()
方法。这样做会向用户显示权限通知;用户必须先授予权限,您才能创建服务。创建前台服务后,您可以调用
MediaProjectionManager.getMediaProjection()
。- 说明
使用
MediaProjection
API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。- 替代方案
如需将媒体流式传输到其他设备,请使用 Google Cast SDK。
mikrofon
- Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
- Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Runtime prerequisites
Request and be granted the
RECORD_AUDIO
runtime permission.- Description
Continue microphone capture from the background, such as voice recorders or communication apps.
Rozmowa telefoniczna
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
phoneCall
- 在清单中声明的权限
FOREGROUND_SERVICE_PHONE_CALL
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_PHONE_CALL
- 运行时前提条件
必须至少满足以下其中一个条件:
- 应用已在其清单文件中声明
MANAGE_OWN_CALLS
权限。
- 应用已在其清单文件中声明
- 应用是通过
ROLE_DIALER
角色的默认拨号器应用。
- 应用是通过
- 说明
使用
ConnectionService
API 继续当前通话。- 替代方案
如果您需要拨打电话、视频通话或 VoIP 通话,不妨考虑使用
android.telecom
库。考虑使用
CallScreeningService
来过滤来电。
Zdalne przesyłanie wiadomości
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
remoteMessaging
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_REMOTE_MESSAGING
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
- Przenoszenie SMS-ów z jednego urządzenia na drugie. Zapewnia ciągłość zadań związanych z wiadomościami przy przełączaniu się na inne urządzenie.
Krótkie usługi
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
shortService
- 在清单中声明的权限
- 无
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- 运行时前提条件
- 无
- 说明
快速完成不可中断或推迟的关键工作。
这种类型有一些独特的特征:
- 只能持续运行一小段时间(大约 3 分钟)。
- 不支持粘性前台服务。
- 无法启动其他前台服务。
- 不需要类型专用权限,不过它仍需要
FOREGROUND_SERVICE
权限。 - 只有当应用当前有资格启动新的前台服务时,
shortService
才能更改为另一种服务类型。 - 前台服务可以随时将其类型更改为
shortService
,届时超时期限将开始。
shortService 的超时时间从调用
Service.startForeground()
开始算起。应用应在发生超时之前调用Service.stopSelf()
或Service.stopForeground()
。否则,系统会调用新的Service.onTimeout()
,让应用有机会调用stopSelf()
或stopForeground()
来停止其服务。调用
Service.onTimeout()
后的短时间内,应用会进入缓存状态,并且不再被视为处于前台,除非用户正在主动与应用互动。应用缓存一小段时间后,服务还未停止,该应用会收到 ANR 消息。ANR 消息提及FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
。出于这些原因,实现Service.onTimeout()
回调被视为一种最佳实践。Android 13 及更低版本中不存在
Service.onTimeout()
回调。如果同一服务在此类设备上运行,则不会出现超时,也不会发生 ANR。确保您的服务在完成处理任务后立即停止,即使它尚未收到Service.onTimeout()
回调也是如此。请务必注意,如果未遵循
shortService
的超时设置,即使应用还有其他有效的前台服务或其他应用生命周期进程,应用也会遇到 ANR。如果应用对用户可见,或满足允许从后台启动前台服务的某一豁免条件,则使用
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
参数再次调用Service.StartForeground()
会将超时时间再延长 3 分钟。如果应用对用户不可见且不满足其中一个豁免条件,则尝试启动其他前台服务(无论其类型如何)都会导致ForegroundServiceStartNotAllowedException
。即使用户为您的应用停用电池优化功能,仍然会受到 shortService FGS 的影响。
如果您启动包含
shortService
类型和另一个前台服务类型的前台服务,系统会忽略shortService
类型声明。不过,该服务仍必须遵守其他声明类型的前提条件。如需了解详情,请参阅前台服务文档。
Specjalne zastosowanie
- 要在清单中声明的前台服务类型
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>
System wykluczony
- Foreground service type to declare in manifest under
android:foregroundServiceType
systemExempted
- Permission to declare in your manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Runtime prerequisites
- None
- Description
Reserved for system applications and specific system integrations, to continue to use foreground services.
To use this type, an app must meet at least one of the following criteria:
- Device is in demo mode state
- App is a Device Owner
- App is a Profiler Owner
- Safety Apps that have the
ROLE_EMERGENCY
role - Device Admin apps
- Apps holding
SCHEDULE_EXACT_ALARM
orUSE_EXACT_ALARM
permission VPN apps (configured using Settings > Network & Internet > VPN)
Otherwise, declaring this type causes the system to throw a
ForegroundServiceTypeNotAllowedException
.
Egzekwowanie zasad Google Play dotyczących korzystania z typów usług na pierwszym planie
如果您的应用以 Android 14 或更高版本为目标平台,您需要在 Play 管理中心的“应用内容”页面(政策 > 应用内容)中声明应用的前台服务类型。如需详细了解如何在 Play 管理中心内声明前台服务类型,请参阅了解前台服务和全屏 intent 要求。