Aby deweloperzy mogli bardziej świadomie definiować usługi na pierwszym planie dla użytkowników, w Androidzie 10 wprowadziliśmy atrybut android:foregroundServiceType
w elemencie <service>
.
Jeśli aplikacja jest kierowana na Androida 14, musi określać odpowiednie typy usług na pierwszym planie. Podobnie jak w poprzednich wersjach Androida, możesz łączyć wiele typów. Ta lista zawiera typy usług na pierwszym planie do wyboru:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
Jeśli przypadek użycia w Twojej aplikacji nie jest powiązany z żadnym z tych typów, zdecydowanie zalecamy przeniesienie logiki tak, aby używała WorkManagera lub zadań przenoszenia danych inicjowanych przez użytkownika.
Typy health, remoteMessaging, shortService, specialUse
i systemExempted
są nowe w Androidzie 14.
Ten fragment kodu zawiera przykładową deklaracja typu usługi na pierwszym planie w pliku manifestu:
<manifest ...>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<application ...>
<service
android:name=".MyMediaPlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="false">
</service>
</application>
</manifest>
Jeśli aplikacja kierowana na Androida 14 nie określa typów danej usługi w pliku manifestu, system zgłosi MissingForegroundServiceTypeException
po wywołaniu funkcji startForeground()
w przypadku tej usługi.
Zadeklaruj nowe uprawnienia do korzystania z typów usług na pierwszym planie
Jeśli aplikacje kierowane na Androida 14 korzystają z usługi na pierwszym planie, muszą zadeklarować określone uprawnienie, które wprowadza (w zależności od typu tej usługi). Te uprawnienia znajdują się w sekcjach oznaczonych jako „Uprawnienia, które musisz zadeklarować w pliku manifestu” w sekcji Zamierzone zastosowania i egzekwowanie poszczególnych typów usług na pierwszym planie na tej stronie.
Wszystkie uprawnienia są zdefiniowane jako normalne uprawnienia i są przyznawane domyślnie. Użytkownicy nie mogą anulować tych uprawnień.
Uwzględnij typ usługi na pierwszym planie w trakcie działania
Sprawdzoną metodą w przypadku aplikacji uruchamiających usługi na pierwszym planie jest używanie wersji ServiceCompat
startForeground()
(dostępnej w systemie Androidx-core 1.12 i nowszych), w której przekazujesz bitową liczbę całkowitą typów usług na pierwszym planie. Możesz przekazać 1 lub więcej par typu.
Zwykle należy zadeklarować tylko te typy, które są wymagane w danym przypadku użycia. Dzięki temu łatwiej jest spełnić oczekiwania systemu dotyczące poszczególnych typów usług na pierwszym planie. Jeśli usługa na pierwszym planie jest uruchamiana od wielu typów, to musi być zgodna z wymaganiami dotyczącymi egzekwowania zasad na poziomie platformy w przypadku wszystkich typów usług.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Jeśli w wywołaniu nie określisz typu usługi na pierwszym planie, domyślnie zostaną użyte wartości zdefiniowane w pliku manifestu. Jeśli w pliku manifestu nie określisz typu usługi, system zgłosi MissingForegroundServiceTypeException
.
Jeśli po uruchomieniu usługa na pierwszym planie wymaga nowych uprawnień, musisz ponownie wywołać metodę startForeground()
i dodać nowe typy usług. Załóżmy np., że aplikacja do fitnessu obsługuje usługę śledzenia biegowego, która zawsze potrzebuje informacji location
, ale może nie potrzebować uprawnień media
. Musisz zadeklarować w pliku manifestu zarówno location
, jak i mediaPlayback
. Jeśli użytkownik rozpocznie uruchomienie i chce tylko śledzić jego lokalizację, aplikacja powinna wywołać metodę startForeground()
i przekazać tylko typ usługi location
. Jeśli użytkownik będzie chciał zacząć odtwarzać dźwięk, wywołaj ponownie polecenie startForeground()
i przekaż plik location|mediaPlayback
.
Sprawdzanie czasu działania systemu
System sprawdza, czy dany rodzaj usług na pierwszym planie jest używany, i potwierdza, czy aplikacja żąda odpowiednich uprawnień w czasie działania lub korzysta z wymaganych interfejsów API.
Na przykład system oczekuje, że aplikacje korzystające z usługi na pierwszym planie typu FOREGROUND_SERVICE_TYPE_LOCATION
będą wysyłać żądania ACCESS_COARSE_LOCATION
lub ACCESS_FINE_LOCATION
.
Oznacza to, że gdy żądają od użytkownika uprawnień i uruchamiają usługi na pierwszym planie, aplikacje muszą wykonać określoną kolejność działań. Należy poprosić o uprawnienia i przyznać je przed próbą wywołania przez aplikację startForeground()
. Aplikacje, które proszą o odpowiednie uprawnienia po uruchomieniu usługi na pierwszym planie, muszą zmienić tę kolejność działań i poprosić o odpowiednie uprawnienia przed uruchomieniem tej usługi.
Szczegółowe informacje o egzekwowaniu zasad na platformie znajdziesz w sekcji „Wymagania dotyczące środowiska wykonawczego” w sekcji o zamierzonych przypadkach użycia i ich egzekwowaniu w przypadku poszczególnych typów usług na pierwszym planie na tej stronie.
Zamierzone przypadki użycia i egzekwowanie zasad w przypadku każdego typu usługi na pierwszym planie
Aby używać danego typu usługi na pierwszym planie, musisz zadeklarować konkretne uprawnienie w pliku manifestu, spełnić określone wymagania w czasie działania, a aplikacja musi spełniać jeden z zamierzonych dla niego zestawów przypadków użycia. W sekcjach poniżej znajdziesz informacje o uprawnieniach, które musisz zadeklarować, o wymaganiach wstępnych dotyczących środowiska wykonawczego oraz o zamierzonych przypadkach użycia poszczególnych typów.
Aparat
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
camera
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_CAMERA
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Wymagania wstępne środowiska wykonawczego
Wysyłanie prośby o przyznanie uprawnień w czasie działania
CAMERA
Uwaga: uprawnienia środowiska wykonawczego
CAMERA
podlegają ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyć usługicamera
na pierwszym planie, gdy aplikacja działa w tle (kilka wyjątków). Więcej informacji znajdziesz w artykule o ograniczeniach dotyczących uruchamiania usług działających na pierwszym planie, które wymagają uprawnień podczas korzystania.- Opis
Nadal korzystaj z kamery w tle, 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 domenie
android:foregroundServiceType
dataSync
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_DATA_SYNC
- Stała do przekazywania 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 zapasowych
- Operacje importu lub eksportu
- Pobierz dane
- Lokalne przetwarzanie plików
- Przesyłanie danych między urządzeniem a chmurą przez sieć
- Alternatywy
Więcej informacji znajdziesz w artykule Alternatywy dla usług działających na pierwszym planie do synchronizacji danych.
Zdrowie
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
health
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_HEALTH
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
- Wymagania wstępne środowiska wykonawczego
Musi być spełniony co najmniej jeden z tych warunków:
Zadeklaruj uprawnienie
HIGH_SAMPLING_RATE_SENSORS
w pliku manifestu.Poproś o przyznanie co najmniej jednego z tych uprawnień w czasie działania:
Uwaga: uprawnienia środowiska wykonawczego
BODY_SENSORS
podlegają ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyć usługi na pierwszym planiehealth
, która korzysta z czujników na ciele, gdy aplikacja działa w tle (z kilkoma wyjątkami). Więcej informacji znajdziesz w artykule o ograniczeniach dotyczących uruchamiania usług działających na pierwszym planie, które wymagają uprawnień podczas korzystania.- Opis
Wszelkie długotrwałe przypadki użycia dotyczące aplikacji z kategorii fitness, np. trackerów do śledzenia ćwiczeń.
Lokalizacja
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w
android:foregroundServiceType
location
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_LOCATION
- Stała przekazu do
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Wymagania wstępne środowiska wykonawczego
Użytkownik musi mieć włączone usługi lokalizacyjne, a aplikacji musi przyznać co najmniej jedno z tych uprawnień w czasie działania aplikacji:
Uwaga: aby sprawdzić, czy użytkownik włączył usługi lokalizacyjne i czy przyznał dostęp do uprawnień czasu działania, użyj funkcji
PermissionChecker#checkSelfPermission()
.Uwaga: uprawnienia czasu działania lokalizacji podlegają ograniczeniom podczas używania. Z tego powodu nie możesz utworzyć usługi na pierwszym planie
location
, gdy aplikacja działa w tle, chyba że otrzymasz uprawnienieACCESS_BACKGROUND_LOCATION
w czasie działania. Więcej informacji znajdziesz w artykule o ograniczeniach uruchamiania usług działających na pierwszym planie, które wymagają uprawnień podczas używania.- Opis
długotrwałe przypadki użycia, które wymagają dostępu do lokalizacji, np. nawigacja i udostępnianie lokalizacji.
- Alternatywy
Jeśli Twoja aplikacja musi być aktywowana, gdy użytkownik dotrze do określonej lokalizacji, rozważ użycie interfejsu API geofence.
Multimedia
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
mediaPlayback
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MEDIA_PLAYBACK
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
- Kontynuuj odtwarzanie dźwięku lub wideo w tle. Obsługa funkcji nagrywania cyfrowego filmu (DVR) na Androidzie TV.
- Alternatywy
- Jeśli korzystasz z obrazu w obrazie, użyj trybu obrazu w obrazie.
Wyświetlanie multimediów
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
mediaProjection
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Wymagania wstępne środowiska wykonawczego
Przed uruchomieniem usługi na pierwszym planie wywołaj metodę
createScreenCaptureIntent()
. Spowoduje to wyświetlenie użytkownikowi powiadomienia o uprawnieniach. Użytkownik musi je przyznać, zanim będzie można utworzyć usługę.Po utworzeniu usługi na pierwszym planie możesz wywołać metodę
MediaProjectionManager.getMediaProjection()
.- Opis
wyświetlać treści na wyświetlaczu innym niż główny lub urządzeniu zewnętrznym za pomocą interfejsów API
MediaProjection
; 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 domenie
android:foregroundServiceType
microphone
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_MICROPHONE
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Wymagania wstępne środowiska wykonawczego
Poproś o przyznanie uprawnień w czasie działania
RECORD_AUDIO
.Uwaga: uprawnienia środowiska wykonawczego
RECORD_AUDIO
podlegają ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyć usługimicrophone
na pierwszym planie, gdy aplikacja działa w tle (kilka wyjątków). Więcej informacji znajdziesz w artykule o ograniczeniach dotyczących uruchamiania usług działających na pierwszym planie, które wymagają uprawnień podczas korzystania.- Opis
Kontynuować nagrywanie mikrofonu w tle, np. przy pomocy dyktafonu lub aplikacji do komunikacji.
Rozmowa telefoniczna
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
phoneCall
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_PHONE_CALL
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Wymagania wstępne środowiska wykonawczego
Musi być spełniony co najmniej jeden z tych warunków:
- Aplikacja zadeklarowała uprawnienie
MANAGE_OWN_CALLS
w swoim pliku manifestu.
- Aplikacja zadeklarowała uprawnienie
- Aplikacja jest domyślną aplikacją telefonu w roli
ROLE_DIALER
.
- Aplikacja jest domyślną aplikacją telefonu w roli
- Opis
Kontynuuj trwające wywołanie za pomocą interfejsów API
ConnectionService
.- Alternatywy
Jeśli chcesz nawiązywać połączenia telefoniczne, wideo lub VoIP, rozważ skorzystanie z biblioteki
android.telecom
.Do filtrowania połączeń możesz używać
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
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
shortService
- Uprawnienia do zadeklarowania w pliku manifestu
- Brak
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Szybko kończ najważniejsze zadania, których nie można przerwać ani odłożyć na później.
Ten typ ma kilka wyjątkowych cech:
- Może być aktywna tylko przez krótki czas (około 3 minuty).
- Brak obsługi usług przyklejonych na pierwszym planie.
- Nie można uruchomić innych usług działających na pierwszym planie.
- Nie wymaga uprawnień dotyczących konkretnego typu, ale nadal wymaga uprawnienia
FOREGROUND_SERVICE
. - Usługa
shortService
może się zmienić na inny typ usługi tylko wtedy, gdy aplikacja kwalifikuje się obecnie do uruchomienia nowej usługi na pierwszym planie. - Usługa na pierwszym planie może w każdej chwili zmienić swój typ na
shortService
. W tym momencie rozpoczyna się limit czasu oczekiwania.
Limit czasu usługi shortService zaczyna się od momentu wywołania metody
Service.startForeground()
. Aplikacja powinna wywołaćService.stopSelf()
lubService.stopForeground()
przed upływem limitu czasu. W przeciwnym razie wywoływany jest nowyService.onTimeout()
, co daje aplikacjom krótką okazję do wywołania metodystopSelf()
lubstopForeground()
w celu zatrzymania działania usługi.W krótkim czasie po wywołaniu funkcji
Service.onTimeout()
aplikacja przechodzi w stan z pamięci podręcznej i nie jest już uznawana za działającą na pierwszym planie, chyba że użytkownik aktywnie z niej korzysta. W krótkim czasie po zapisaniu aplikacji w pamięci podręcznej, a aplikacja nie została zatrzymana, aplikacja otrzymuje błąd ANR. Wiadomość o błędzie ANR zawiera informację o elemencieFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. Dlatego wdrożenie wywołania zwrotnegoService.onTimeout()
uznaje się za sprawdzoną metodą.Wywołanie zwrotne
Service.onTimeout()
nie występuje na Androidzie 13 i starszych wersjach. Jeśli na takich urządzeniach ta sama usługa działa, nie dochodzi do jej przekroczenia limitu czasu ani błędów ANR. Upewnij się, że usługa zatrzymuje się natychmiast po zakończeniu zadania przetwarzania, nawet jeśli nie odebrała jeszcze wywołania zwrotnegoService.onTimeout()
.Pamiętaj, że jeśli limit czasu
shortService
nie jest przestrzegany, w aplikacji wystąpi błąd ANR, nawet jeśli mają uruchomione inne prawidłowe usługi na pierwszym planie lub inne uruchomione procesy cyklu życia aplikacji.Jeśli aplikacja jest widoczna dla użytkownika lub spełnia jedno z wyjątków, które zezwalają na uruchamianie usług działających na pierwszym planie w tle, ponowne wywołanie metody
Service.StartForeground()
z parametremFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
wydłuża czas oczekiwania o kolejne 3 minuty. Jeśli aplikacja nie jest widoczna dla użytkownika i nie spełnia jednego z wyjątków, każda próba uruchomienia kolejnej usługi na pierwszym planie (niezależnie od typu) powoduje wywołanieForegroundServiceStartNotAllowedException
.Jeśli użytkownik wyłączy optymalizację baterii w Twojej aplikacji, nadal na niego wpływa limit czasu usługi shortService FGS.
Jeśli uruchomisz usługę działającej na pierwszym planie, która zawiera typ
shortService
i inny typ tej usługi, system zignoruje deklarację typushortService
. Usługa musi jednak spełniać wymagania wstępne innych zadeklarowanych typów. Więcej informacji znajdziesz w dokumentacji usług działających na pierwszym planie.
Specjalne zastosowanie
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w domenie
android:foregroundServiceType
specialUse
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_SPECIAL_USE
- Stała do przekazywania do:
startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Obejmuje wszystkie prawidłowe przypadki użycia usług na pierwszym planie, których nie obejmują inne typy takich usług.
Oprócz zadeklarowania typu usługi na pierwszym planie
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
deweloperzy powinni zadeklarować przypadki użycia w pliku manifestu. Aby to zrobić, określają element<property>
w elemencie<service>
. Te wartości i odpowiadające im przypadki użycia są sprawdzane po przesłaniu aplikacji w Konsoli Google Play. Podane przez Ciebie przypadki użycia mają charakter swobodny – pamiętaj, aby podać wystarczającą ilość informacji, aby weryfikator mógł zrozumieć, dlaczego musisz użyć typuspecialUse
.<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
- Typ usługi na pierwszym planie do zadeklarowania w pliku manifestu w
android:foregroundServiceType
systemExempted
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- Stała przekazu do
startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Zarezerwowana dla aplikacji systemowych i określonych integracji systemów, aby nadal korzystać z usług na pierwszym planie.
Aby korzystać z 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 związane z bezpieczeństwem, które mają rolę
ROLE_EMERGENCY
- aplikacje Administrator urządzenia,
- aplikacje obsługujące
SCHEDULE_EXACT_ALARM
lubUSE_EXACT_ALARM
, użytkownik: , usługa na pierwszym planie, aby kontynuowała alarmy w tle, w tym alarmy tylko z czujnikiem haptycznym. aplikacje VPN (konfigurowane za pomocą Ustawienia > Sieć i internet > VPN);
W przeciwnym razie zadeklarowanie tego typu powoduje, że system przekazuje
ForegroundServiceTypeNotAllowedException
Egzekwowanie zasad Google Play związanych z używaniem typów usług na pierwszym planie
Jeśli Twoja aplikacja jest kierowana na Androida 14 lub nowszego, musisz zadeklarować typy jej usług na pierwszym planie na stronie treści aplikacji w Konsoli Play (Zasady > Zawartość aplikacji). Więcej informacji o deklarowaniu typów usług na pierwszym planie w Konsoli Play znajdziesz w tym artykule.