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.

Uwaga: w wielu przypadkach zamiast tworzyć określony typ usługi na pierwszym planie możesz użyć specjalnie do tego celu przeznaczonych interfejsów API. Jeśli dostępne są interfejsy API przeznaczone do konkretnych celów, zwykle są one lepszym wyborem niż tworzenie usługi działającej na pierwszym planie. Te interfejsy API są wymienione w sekcjach Alternatywne rozwiązania w odpowiednich

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.

Uwaga: uprawnienie czasu działania CAMERA podlega ograniczeniom dotyczącym używania. Z tego powodu nie możesz utworzyć usługi camera działającej na pierwszym planie, gdy aplikacja działa w tle, ani uruchomić usługi camera działającej na pierwszym planie z odbiornika BOOT_COMPLETED, z kilkoma wyjątkami. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas używania.

Opis

Dalsze korzystanie w tle z aparatu, np. w aplikacjach 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

运行时前提条件

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

• 在清单中至少声明以下其中一项权限：

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

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

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• 调用 UsbManager.requestPermission()

说明

与需要蓝牙、NFC、IR、USB 或网络连接的外部设备进行互动。

注意 ：如果您的应用执行投影或远程消息传递操作，请改用相应的媒体投影或远程消息传递类型。

替代方案

如果您的应用需要向外部设备持续传输数据，请考虑改用配套设备管理器。使用配套设备感知 API，可帮助您的应用在配套设备在范围内时保持运行。

如果您的应用需要扫描蓝牙设备，请考虑改用 Bluetooth Scan API。

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 do przekazania do startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Wymagania wstępne dotyczące środowiska wykonawczego

Brak

Opis

Operacje przesyłania danych, takie jak:

• Przesyłanie i pobieranie danych
• Operacje tworzenia i przywracania kopii zapasowych
• Operacje importowania i eksportowania
• Pobieranie danych
• Przetwarzanie plików lokalnych
• Przesyłanie danych między urządzeniem a chmurą przez sieć

Uwaga: aplikacje kierowane na Androida 15 lub nowszego nie mogą uruchamiać usługi pierwszego planu synchronizacji danych z odbiornika BOOT_COMPLETED. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie przez odbiorniki transmisji BOOT_COMPLETED.

Alternatywy

Szczegółowe informacje znajdziesz w artykule Alternatywy dla usług na pierwszym planie do synchronizacji danych.

Stan

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

health

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_HEALTH

Stała wartość przekazywana do funkcji startForeground()

FOREGROUND_SERVICE_TYPE_HEALTH

Wymagania wstępne środowiska wykonawczego

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

• Zadeklaruj uprawnienie HIGH_SAMPLING_RATE_SENSORS w pliku manifestu.

• Wymagane jest co najmniej 1 z tych uprawnień:

  • BODY_SENSORS w interfejsie API 35 lub starszym
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

Uwaga: uprawnienia do odczytu BODY_SENSORS i uprawnienia oparte na czujnikach są ograniczone w czasie działania. Z tego powodu nie możesz utworzyć usługi na pierwszym planie health, która używa czujników ciała, gdy aplikacja działa w tle, chyba że masz uprawnienia BODY_SENSORS_BACKGROUND (między poziomem interfejsu API 33 a poziomem interfejsu API 35) lub READ_HEALTH_DATA_IN_BACKGROUND (poziom interfejsu API 36). Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania.

Opis

Wszystkie długotrwałe przypadki użycia, które obsługują aplikacje z kategorii fitness, np. monitory aktywności.

Lokalizacja

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

location

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_LOCATION

stała wartość przekazywana do startForeground(),

FOREGROUND_SERVICE_TYPE_LOCATION

Wymagania wstępne środowiska wykonawczego

Użytkownik musi mieć włączone usługi lokalizacyjne, a aplikacja musi mieć co najmniej 1 z tych uprawnień w czasie działania:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

Uwaga: aby sprawdzić, czy użytkownik ma włączone usługi lokalizacji i czy udzielił dostępu do uprawnień w czasie działania, użyj PermissionChecker#checkSelfPermission()

Uwaga: uprawnienia do lokalizacji w czasie działania podlegają ograniczeniom podczas używania. Z tego powodu nie możesz utworzyć usługi location na pierwszym planie, gdy aplikacja działa w tle, chyba że masz uprawnienie do wykonywania operacji w czasie działania ACCESS_BACKGROUND_LOCATION. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania

.

Opis

Długotrwałe przypadki użycia, które wymagają dostępu do lokalizacji, takie jak nawigacja i udostępnianie lokalizacji.

Alternatywy

Jeśli aplikacja ma być uruchamiany, gdy użytkownik dotrze do określonych lokalizacji, rozważ użycie interfejsu 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 do przekazania do startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK

Wymagania wstępne dotyczące środowiska wykonawczego

Brak

Opis

Dotyczy to ciągłego odtwarzania dźwięku lub wideo w tle. obsługiwać funkcję cyfrowego nagrywania wideo (DVR) na Androidzie TV.

Uwaga: aplikacje kierowane na Androida 15 lub nowszego nie mogą uruchamiać usługi działającej na pierwszym planie do odtwarzania multimediów z odbiornika BOOT_COMPLETED. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie przez odbiorniki transmisji BOOT_COMPLETED.

Alternatywy

Jeśli wyświetlasz film w trybie obrazu w obrazie, użyj trybu obrazu w obrazie.

Przetwarzane materiały

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

mediaProcessing

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_MEDIA_PROCESSING

stała wartość przekazywana do startForeground(),

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Wymagania wstępne środowiska wykonawczego

Brak

Opis

Usługa do wykonywania czasochłonnych operacji na zasobach multimedialnych, takich jak konwertowanie multimediów na różne formaty. System zezwala tej usłudze na ograniczony czas działania. W normalnych okolicznościach limit czasu wynosi 6 godzin na 24 godziny. Ten limit jest wspólny dla wszystkich mediaProcessing usług na pierwszym planie w aplikacji.

Aplikacja powinna ręcznie zatrzymać usługę przetwarzania multimediów w takich sytuacjach:

• Gdy operacja transkodowania zostanie zakończona lub osiągnie stan błędu, usługa powinna wywołać Service.stopForeground() i Service.stopSelf(), aby całkowicie zatrzymać usługę.

Po upływie limitu czasu system wywołuje metodę Service.onTimeout(int, int) usługi. W tym momencie usługa ma kilka sekund na wywołanie funkcji Service.stopSelf(). Jeśli usługa nie wywołuje funkcji Service.stopSelf(), wystąpi ANR z komunikatem o błędzie: „Usługa na pierwszym planie <fgs_type> nie zatrzymała się w czasie swojego limitu czasu: <component_name>”.

Uwaga: funkcja Service.onTimeout(int, int) jest niedostępna na Androidzie 14 lub starszym. Na urządzeniach z tymi wersjami, jeśli usługa przetwarzania multimediów osiągnie limit czasu, system natychmiast przeniesie aplikację do pamięci podręcznej. Z tego powodu aplikacja nie powinna czekać na powiadomienie o przekroczeniu limitu czasu. Zamiast tego należy zakończyć usługę na pierwszym planie lub jak najszybciej zmienić ją na usługę działającą w tle.

Wyświetlanie multimediów

Foreground service type to declare in manifest under

android:foregroundServiceType

mediaProjection

Permission to declare in your manifest

FOREGROUND_SERVICE_MEDIA_PROJECTION

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Runtime prerequisites

Call the createScreenCaptureIntent() method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.

After you have created the foreground service, you can call MediaProjectionManager.getMediaProjection().

Description

Project content to non-primary display or external device using the MediaProjection APIs. This content doesn't have to be exclusively media content.

Note: Apps that target Android 15 or higher are not allowed to launch a media projection foreground service from a BOOT_COMPLETED broadcast receiver. For more information, see Restrictions on BOOT_COMPLETED broadcast receivers launching foreground services.

Alternatives

To stream media to another device, use the Google Cast SDK.

Mikrofon

要在清单中声明的前台服务类型，位于

android:foregroundServiceType

microphone

要在清单中声明的权限

FOREGROUND_SERVICE_MICROPHONE

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_MICROPHONE

运行时前提条件

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

注意： RECORD_AUDIO 运行时权限受“使用时”限制。因此，当应用在后台运行时，您无法创建 microphone 前台服务，也无法从 BOOT_COMPLETED 接收器启动 microphone 前台服务，但有少数例外情况。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

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

Rozmowa telefoniczna

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

phoneCall

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_PHONE_CALL

Stała do przekazania do startForeground()

FOREGROUND_SERVICE_TYPE_PHONE_CALL

Wymagania wstępne dotyczące środowiska wykonawczego

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

• Aplikacja zadeklarowała uprawnienia MANAGE_OWN_CALLS w pliku manifestu.

• Aplikacja jest domyślną aplikacją telefoniczną dzięki roli ROLE_DIALER.

Uwaga: aplikacje kierowane na Androida 15 lub nowszego nie mogą uruchamiać usługi działającej na pierwszym planie, która umożliwia wykonywanie połączeń telefonicznych, z odbiornika BOOT_COMPLETED. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie przez odbiorniki transmisji BOOT_COMPLETED.

Opis

Kontynuuj trwające połączenie za pomocą interfejsów ConnectionService API.

Alternatywy

Jeśli chcesz wykonywać połączenia telefoniczne, wideo lub VoIP, rozważ użycie biblioteki android.telecom.

Rozważ użycie CallScreeningService do filtrowania połączeń.

Zdalne przesyłanie wiadomości

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

remoteMessaging

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_REMOTE_MESSAGING

stała wartość przekazywana do startForeground(),

FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING

Wymagania wstępne środowiska wykonawczego

Brak

Opis

Przenoszenie wiadomości tekstowych z jednego urządzenia na drugie. Dotyczy to pomocy w ciągłości wykonywania przez użytkownika zadań związanych z wiadomościami przy przełączaniu się na inne urządzenie.

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

Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w sekcji

android:foregroundServiceType

specialUse

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_SPECIAL_USE

stała wartość przekazywana do startForeground(),

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

Wymagania wstępne środowiska wykonawczego

Brak

Opis

Obejmuje wszystkie prawidłowe przypadki użycia usługi na pierwszym planie, które nie są objęte innymi typami usług na pierwszym planie.

Oprócz zadeklarowania FOREGROUND_SERVICE_TYPE_SPECIAL_USEtypu usługi na pierwszym planie deweloperzy powinni zadeklarować przypadki użycia w pliku manifestu. W tym celu określają element <property> w elemencie <service>. Te wartości i odpowiednie przypadki użycia są sprawdzane podczas przesyłania aplikacji w Konsoli Google Play. Podane przez Ciebie przypadki użycia są niesformalne. Pamiętaj, aby podać wystarczającą ilość informacji, aby zweryfikować, dlaczego musisz używać typu 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

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 or USE_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 używania 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.