Typy usług działających na pierwszym planie

Począwszy od Androida 14 (interfejs API na poziomie 34), musisz zadeklarować odpowiedni typ usługi dla każdej usługi działającej na pierwszym planie. Oznacza to, że musisz zadeklarować typ usługi w pliku manifestu aplikacji, a także poprosić o odpowiednie uprawnienia usługi na pierwszym planie dla tego typu (oprócz prośby o uprawnienia FOREGROUND_SERVICE). Dodatkowo w zależności od typu usługi na pierwszym planie przed jej uruchomieniem może być konieczne poproszenie o uprawnienia w czasie działania.

typach usług działających na pierwszym planie.

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 do przekazania do startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Wymagania wstępne dotyczące środowiska wykonawczego

Poproś o uprawnienie czasu działania CAMERA i uzyskaj je.

Opis

Dalsze korzystanie w tle z aparatu, np. w aplikacjach 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 sekcji
android:foregroundServiceType
connectedDevice
Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_CONNECTED_DEVICE
stała wartość przekazywana do startForeground(),
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Wymagania wstępne środowiska wykonawczego

Musi być spełniony co najmniej 1 z tych warunków:

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 ciągle przesyłać dane na urządzenie zewnętrzne, rozważ użycie menedżera urządzenia towarzyszącego. Użyj interfejsu API obecności urządzenia towarzyszącego, aby aplikacja działała, gdy urządzenie towarzyszące znajduje się w zasięgu.

Jeśli Twoja aplikacja musi skanować urządzenia Bluetooth, rozważ użycie interfejsu API skanowania Bluetooth.

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
运行时前提条件

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

说明

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

Lokalizacja

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

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

说明

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

替代方案

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

Multimedia

要在清单中声明的前台服务类型，位于
android:foregroundServiceType
mediaPlayback
要在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
运行时前提条件
无
说明

在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。

替代方案

如果您要显示画中画视频，请使用画中画模式。

Przetwarzane materiały

要在清单中的以下位置声明的前台服务类型
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 或更低版本。在搭载这些版本的设备上，如果媒体处理服务达到超时期限，系统会立即缓存应用。因此，您的应用不应等待收到超时通知。相反，它应在适当情况下尽快终止前台服务或将其更改为后台服务。

Wyświetlanie multimediów

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
mediaProjection
Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MEDIA_PROJECTION
Stała do przekazania do startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Wymagania wstępne dotyczące środowiska wykonawczego

Przed uruchomieniem usługi na pierwszym planie wywołaj metodę createScreenCaptureIntent(). W ten sposób wyświetlisz użytkownikowi powiadomienie o uprawnieniach. Zanim utworzysz usługę, użytkownik musi przyznać uprawnienia.

Po utworzeniu usługi na pierwszym planie możesz wywołać MediaProjectionManager.getMediaProjection().

Opis

Dotyczy to wyświetlania treści na wyświetlaczu innym niż główny lub urządzeniu zewnętrznym przy użyciu interfejsów MediaProjection API. Nie muszą to być wyłącznie treści multimedialne.

Alternatywy

Aby przesyłać strumieniowo multimedia na inne urządzenie, użyj pakietu Google Cast SDK.

Mikrofon

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

请求并被授予 RECORD_AUDIO 运行时权限。

说明

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

Rozmowa telefoniczna

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

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

  • 应用通过 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ótka obsługa

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji
android:foregroundServiceType
shortService
Uprawnienia do zadeklarowania w pliku manifestu
Brak
stała wartość przekazywana do startForeground(),
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Wymagania wstępne środowiska wykonawczego
Brak
Opis

Szybkie ukończenie ważnych zadań, które nie mogą zostać przerwane ani przełożone.

Ten typ ma kilka unikalnych cech:

  • może być uruchomiony tylko przez krótki czas (około 3 minut);
  • Nieobsługiwane są przypięte usługi na pierwszym planie.
  • Nie można uruchomić innych usług na pierwszym planie.
  • Nie wymaga uprawnień związanych z typem, ale nadal wymaga uprawnień FOREGROUND_SERVICE.
  • Usługa shortService może zmienić typ usługi na inny tylko wtedy, gdy aplikacja może obecnie uruchomić nową usługę na pierwszym planie.
  • Usługa na pierwszym planie może w dowolnym momencie zmienić typ na shortService, co powoduje rozpoczęcie okresu oczekiwania.

Limit czasu dla krótkiej usługi rozpoczyna się od momentu wywołania funkcji Service.startForeground(). Aplikacja powinna wywołać funkcję Service.stopSelf() lub Service.stopForeground() przed przekroczeniem limitu czasu. W przeciwnym razie wywoływana jest nowa funkcja Service.onTimeout(), która daje aplikacjom krótką możliwość wywołania funkcji stopSelf() lub stopForeground() w celu zatrzymania usługi.

Krótko po wywołaniu funkcji Service.onTimeout() aplikacja przechodzi w stan buforowania i nie jest już uważana za aplikację na pierwszym planie, chyba że użytkownik aktywnie z nią współpracuje. Krótko po buforowaniu aplikacji, jeśli usługa nie została zatrzymana, aplikacja otrzymuje ANR. Komunikat ANR zawiera wzmiankę o FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Z tych powodów sprawdzoną metodą jest implementowanie funkcji Service.onTimeout() callback.

Funkcja Service.onTimeout() nie jest dostępna w Androidzie 13 i starszych. Jeśli ta sama usługa działa na takich urządzeniach, nie ma limitu czasu ani nie powoduje ANR. Upewnij się, że usługa zatrzymuje się, gdy tylko zakończy przetwarzanie zadania, nawet jeśli nie otrzymała jeszcze wywołania zwrotnego Service.onTimeout().

Pamiętaj, że jeśli nie będziesz przestrzegać limitu czasu shortService, aplikacja będzie generować błąd ANR, nawet jeśli ma inne prawidłowe usługi na pierwszym planie lub inne procesy cyklu życia aplikacji.

Jeśli aplikacja jest widoczna dla użytkownika lub spełnia jedno z wyjątków, które umożliwiają uruchamianie usług na pierwszym planie w tle, ponowne wywołanie funkcji Service.StartForeground() z parametrem FOREGROUND_SERVICE_TYPE_SHORT_SERVICE wydłuża czas oczekiwania o kolejne 3 minuty. Jeśli aplikacja jest niewidoczna dla użytkownika i nie spełnia żadnego z wyjątków, każda próba uruchomienia innej usługi na pierwszym planie, niezależnie od jej typu, powoduje błąd ForegroundServiceStartNotAllowedException.

Jeśli użytkownik wyłączy optymalizację baterii w aplikacji, nadal będzie ona podlegać limitowi czasu krótkiej usługi FGS.

Jeśli uruchomisz usługę na pierwszym planie, która obejmuje typ shortService i inny typ usługi na pierwszym planie, system zignoruje deklarację typu shortService. Usługa musi jednak spełniać wymagania wstępne innych zadeklarowanych typów. Więcej informacji znajdziesz w dokumentacji dotyczącej usług na pierwszym planie.

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>

Wyjątek systemowy

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

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

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

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.