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
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
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
connectedDevice
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_CONNECTED_DEVICE
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
- Wymagania wstępne środowiska wykonawczego
Musi być spełniony co najmniej jeden z tych warunków:
Zadeklaruj w pliku manifestu co najmniej jedno z tych uprawnień:
Poproś o przyznanie co najmniej jednego z tych uprawnień w czasie działania:
Zadzwoń pod numer
UsbManager.requestPermission()
- Opis
Dotyczy to interakcji z urządzeniami zewnętrznymi, które wymagają łączności Bluetooth, NFC, podczerwieni, USB lub połączenia sieciowego.
- Alternatywy
Jeśli aplikacja musi stale przesyłać dane na urządzenie zewnętrzne, rozważ użycie menedżera urządzeń towarzyszących. Użyj interfejsu API obsługi towarzyszącej urządzenia, aby Twoja aplikacja działała, gdy urządzenie towarzyszące znajduje się w zasięgu.
Jeśli aplikacja musi skanować w poszukiwaniu urządzeń Bluetooth, rozważ użycie interfejsu API skanowania Bluetooth.
Synchronizowanie danych
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
dataSync
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_DATA_SYNC
- Stała wartość przekazywana do
startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
operacje przenoszenia danych, takie jak:
- Przesyłanie lub pobieranie danych
- Operacje tworzenia i przywracania kopii zapasowej
- operacje importowania i eksportowania,
- Pobieranie danych
- Przetwarzanie plików lokalnych
- Przenoszenie danych między urządzeniem a chmurą przez sieć
- Alternatywy
Więcej informacji znajdziesz w artykule Alternatywy dla usług na pierwszym planie synchronizujących dane.
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
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
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
mediaProcessing
- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PROCESSING
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
- 运行时前提条件
- 无
- 说明
用于对媒体资源执行耗时操作的服务,例如将媒体转换为不同格式。系统允许此服务有有限的运行时间;在正常情况下,此时间限制为每 24 小时 6 小时。(此限制由应用的所有
mediaProcessing
前台服务共享。)您的应用应在以下情况下手动停止媒体处理服务:
- 当转码操作完成或达到失败状态时,让服务调用
Service.stopForeground()
和Service.stopSelf()
以彻底停止服务。
- 当转码操作完成或达到失败状态时,让服务调用
如果达到超时期限,系统会调用服务的
Service.onTimeout(int, int)
方法。此时,服务有几秒钟时间来调用Service.stopSelf()
。如果服务未调用Service.stopSelf()
,将发生 ANR,并显示以下错误消息:“<fgs_type> 的前台服务未在其超时内停止:<component_name>”。注意:
Service.onTimeout(int, int)
不适用于 Android 14 或更低版本。在运行这些版本的设备上,如果媒体处理服务达到超时期限,系统会立即缓存应用。因此,您的应用不应等待收到超时通知。而是应尽快终止前台服务或将其更改为后台服务。
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
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
microphone
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MICROPHONE
- Stała wartość przekazywana do
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Wymagania wstępne środowiska wykonawczego
Poproś o przyznanie uprawnień czasu działania
RECORD_AUDIO
. .
- Opis
Kontynuowanie rejestrowania dźwięku przez mikrofon w tle, np. w nagrywarkach głosowych lub aplikacjach do komunikacji.
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
- 要在其清单中声明的前台服务类型
android:foregroundServiceType
remoteMessaging
- 在清单中声明的权限
FOREGROUND_SERVICE_REMOTE_MESSAGING
- 要传递给
startForeground()
的常量 FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
- 运行时前提条件
- 无
- 说明
- 将短信从一台设备转移到另一台设备。在用户切换设备时,帮助确保用户消息任务的连续性。
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
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w
android:foregroundServiceType
specialUse
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_SPECIAL_USE
- Stała przekazu do
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Obejmuje wszystkie prawidłowe przypadki użycia usług działających na pierwszym planie, których nie obejmują inne typów usług na pierwszym planie.
Oprócz zadeklarowania
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
typu usługi na pierwszym planie, deweloperzy powinni zadeklarować przypadki użycia w sekcji pliku manifestu. Aby to zrobić, określają element<property>
w parametrze Element<service>
. Te wartości i odpowiadające im przypadki użycia to sprawdzone podczas przesyłania aplikacji w Konsoli Google Play. Zastosowanie podane przez Ciebie przypadki są swobodne. Pamiętaj, aby podać odpowiednio dużo pozwalające weryfikatorowi sprawdzić, dlaczego warto użyć kartyspecialUse
typu.<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 zwolniony z odpowiedzialności
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
systemExempted
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Zarezerwowany na potrzeby aplikacji systemowych i określonych integracji systemowych, aby mogły nadal korzystać z usług działających na pierwszym planie.
Aby użyć tego typu, aplikacja musi spełniać co najmniej jedno z tych kryteriów:
- Urządzenie działa w trybie demonstracyjnym
- Aplikacja jest właścicielem urządzenia
- Aplikacja jest właścicielem profilu
- Aplikacje zabezpieczające z rolą
ROLE_EMERGENCY
- aplikacje do zarządzania urządzeniem,
- Aplikacje z uprawnieniami
SCHEDULE_EXACT_ALARM
lubUSE_EXACT_ALARM
Aplikacje VPN (skonfigurowane w sekcji Ustawienia > Sieć i internet > VPN)
W przeciwnym razie zadeklarowanie tego typu spowoduje zgłoszenie błędu
ForegroundServiceTypeNotAllowedException
.
Egzekwowanie zasad Google Play dotyczących korzystania z typów usług na pierwszym planie
Jeśli Twoja aplikacja jest kierowana na Androida 14 lub nowszego, musisz zadeklarować typy usług na pierwszym planie w Konsoli Play na stronie „Zawartość aplikacji” (Zasady > Zawartość aplikacji). Więcej informacji o deklarowaniu typów usług na pierwszym planie w Konsoli Play znajdziesz w artykule Omówienie wymagań dotyczących usług działających na pierwszym planie i intencji pełnoekranowych.