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 uprawnienie usługi na pierwszym planie dla tego typu (oprócz prośby o uprawnienie 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.
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 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 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ć
- 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 starszymREAD_HEART_RATE
READ_SKIN_TEMPERATURE
READ_OXYGEN_SATURATION
ACTIVITY_RECOGNITION
- 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:
.
- 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;
- Alternatywy
Jeśli wyświetlasz film w trybie obrazu w obrazie, użyj opcji Tryb obrazu w obrazie.
Przetwarzane materiały
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
mediaProcessing
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MEDIA_PROCESSING
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Usługa do wykonywania czasochłonnych operacji na zasobach medialnych, takich jak konwersja multimediów na różne formaty. System zezwala na uruchomienie tej usługi przez ograniczony czas. W normalnych okolicznościach ten limit czasu wynosi 6 godzin z każdej 24 godzin. Ten limit jest wspólny dla wszystkich działających na pierwszym planie usług
mediaProcessing
.Aplikacja powinna ręcznie zatrzymać usługę przetwarzania multimediów w tym scenariuszu:
- Gdy operacja transkodowania zakończy się lub dojdzie do błędu, wywołaj usługę
Service.stopForeground()
iService.stopSelf()
, aby całkowicie zatrzymać usługę.
- Gdy operacja transkodowania zakończy się lub dojdzie do błędu, wywołaj usługę
Po upływie tego czasu system wywołuje metodę
Service.onTimeout(int, int)
usługi. W tej chwili usługa ma kilka sekund na wywołanieService.stopSelf()
. Jeśli usługa nie wywołaService.stopSelf()
, wystąpi błąd ANR z tym komunikatem o błędzie: „Usługa na pierwszym planie <fgs_type> nie została zatrzymana w ramach swojego limitu czasu: <component_name>”.Uwaga: usługa
Service.onTimeout(int, int)
jest niedostępna na urządzeniach z Androidem 14 lub starszym. Gdy usługa przetwarzania multimediów osiągnie limit czasu na urządzeniach z tymi wersjami, system natychmiast zapisze aplikację w pamięci podręcznej. Z tego powodu aplikacja nie powinna czekać na powiadomienie o przekroczeniu limitu czasu. Zamiast tego jak najszybciej powinien zakończyć działanie usługi na pierwszym planie lub zmienić ją w usługę działającą w tle.
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
- 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 do przekazania do
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Wymagania wstępne dotyczące środowiska wykonawczego
Poproś o uprawnienie czasu działania
RECORD_AUDIO
i uzyskaj je.- Opis
Dotyczy to ciągłego nagrywania dźwięku w tle, np. w przypadku dyktafonów lub aplikacji do komunikacji.
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 zadeklarowała uprawnienia
- Aplikacja jest domyślną aplikacją telefoniczną w ramach roli
ROLE_DIALER
.
- Aplikacja jest domyślną aplikacją telefoniczną w ramach roli
- Opis
Kontynuuj trwające połączenie za pomocą interfejsów
ConnectionService
API.- Alternatywy
Jeśli chcesz wykonywać połączenia telefoniczne, wideo lub VoIP, użyj 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 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ótka obsługa
- Foreground service type to declare in manifest under
android:foregroundServiceType
shortService
- Permission to declare in your manifest
- None
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Runtime prerequisites
- None
- Description
Quickly finish critical work that cannot be interrupted or postponed.
This type has some unique characteristics:
- Can only run for a short period of time (about 3 minutes).
- No support for sticky foreground services.
- Cannot start other foreground services.
- Doesn't require a type-specific permission, though it still
requires the
FOREGROUND_SERVICE
permission. - A
shortService
can only change to another service type if the app is currently eligible to start a new foreground service. - A foreground service can change its type to
shortService
at any time, at which point the timeout period begins.
The timeout for shortService begins from the moment that
Service.startForeground()
is called. The app is expected to callService.stopSelf()
orService.stopForeground()
before the timeout occurs. Otherwise, the newService.onTimeout()
is called, giving apps a brief opportunity to callstopSelf()
orstopForeground()
to stop their service.A short time after
Service.onTimeout()
is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentionsFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. For these reasons, it's considered best practice to implement theService.onTimeout()
callback.The
Service.onTimeout()
callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received theService.onTimeout()
callback yet.It's important to note that if the timeout of the
shortService
is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling
Service.StartForeground()
again with theFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes aForegroundServiceStartNotAllowedException
.If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.
If you start a foreground service that includes the
shortService
type and another foreground service type, the system ignores theshortService
type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.
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>
Wyjątek systemowy
- 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 używania typów usług działających 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.