Aby pomóc deweloperom w bardziej celowym definiowaniu usług na pierwszym planie, które są widoczne dla użytkownika, w Androidzie 10 wprowadzono atrybut android:foregroundServiceType
w elemencie <service>
.
Jeśli aplikacja jest kierowana na Androida 14, musi zawierać odpowiednie typy usług działających na pierwszym planie. Podobnie jak w poprzednich wersjach Androida, można łączyć różne typy. Na tej liście znajdziesz typy usług działających na pierwszym planie:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
Jeśli przypadki użycia w aplikacji nie są powiązane z żadnym z tych typów, zdecydowanie zalecamy przeniesienie logiki na WorkManager lub zadania przesyłania danych inicjowane przez użytkownika.
Typy health, remoteMessaging, shortService, specialUse
i systemExempted
to nowe w Androidzie 14.
Ten fragment kodu zawiera przykładową deklarację 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 definiuje typów danej usługi w pliku manifestu, system zgłosi błąd MissingForegroundServiceTypeException
po wywołaniu startForeground()
dla 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 na podstawie typu usługi na pierwszym planie, który jest wprowadzany w Androidzie 14. Te uprawnienia są widoczne w sekcji „uprawnienia, które musisz zadeklarować w pliku manifestu” w sekcji przeznaczone przypadki użycia i wdrożenie w przypadku każdego typu usługi 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
Najlepszym rozwiązaniem w przypadku aplikacji uruchamiających usługi na pierwszym planie jest użycie wersji ServiceCompat
pakietu startForeground()
(dostępnego w pakiecie androidx-core w wersji 1.12 lub nowszej), w której przekazujesz za pomocą funkcji bitwise integer typy usług na pierwszym planie. Możesz przekazać co najmniej 1 wartość typu.
Zazwyczaj należy zadeklarować tylko typy wymagane w konkretnym przypadku użycia. Ułatwia to spełnienie oczekiwań systemu w odniesieniu do poszczególnych typów usług na pierwszym planie. Jeśli usługi działające na pierwszym planie uruchamiają się w kilku typach, muszą być zgodne z wymaganiami dotyczącymi egzekwowania zasad na platformie obowiązującymi w przypadku wszystkich typów.
ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Jeśli w wywołaniu nie określono typu usługi na pierwszym planie, domyślnie przyjmuje się wartości zdefiniowane w pliku manifestu. Jeśli w pliku manifestu nie określisz typu usługi, system zgłosi błąd MissingForegroundServiceTypeException
.
Jeśli usługa na pierwszym planie potrzebuje nowych uprawnień po uruchomieniu, ponownie wywołaj funkcję startForeground()
i dodaj nowe typy usług. Załóżmy na przykład, że aplikacja fitness uruchamia usługę śledzenia biegania, która zawsze potrzebuje informacji location
, ale może lub nie musi wymagać uprawnień media
. W pliku manifestu musisz zadeklarować zarówno location
, jak i mediaPlayback
. Jeśli użytkownik rozpocznie bieg i chce tylko śledzić swoją lokalizację, aplikacja powinna wywołać metodę startForeground()
, przekazując tylko typ usługi location
. Następnie, jeśli użytkownik chce zacząć odtwarzać dźwięk, wywołaj ponownie startForeground()
i przekaż location|mediaPlayback
.
Sprawdzanie czasu działania systemu
System sprawdza, czy typy usług na pierwszym planie są używane prawidłowo, i sprawdza, czy aplikacja poprosiła o odpowiednie uprawnienia do czasu wykonywania lub używa wymaganych interfejsów API.
Na przykład system oczekuje, że aplikacje korzystające z usługi na pierwszym planie typu FOREGROUND_SERVICE_TYPE_LOCATION
poproszą o uprawnienia ACCESS_COARSE_LOCATION
lub ACCESS_FINE_LOCATION
.
Oznacza to, że aplikacje muszą stosować bardzo konkretny porządek operacji podczas proszenia o przyznanie uprawnień przez użytkownika i uruchamiania usług na pierwszym planie. Aplikacja musi poprosić o uprawnienia i otrzymać je przed próbą nawiązania połączenia z numerem startForeground()
. Aplikacje, które proszą o odpowiednie uprawnienia po uruchomieniu usługi na pierwszym planie, muszą zmienić kolejność operacji i poprosić o uprawnienia przed uruchomieniem usługi na pierwszym planie.
Szczegóły dotyczące egzekwowania zasad platformy znajdziesz w sekcji „Wymagania w czasie wykonywania” w sekcji przeznaczone zastosowania i egzekwowanie zasad dla każdego typu usługi 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ć w pliku manifestu odpowiednie uprawnienie, spełnić określone wymagania dotyczące czasu wykonywania, a także dostosować aplikację do jednego z przewidywanych zestawów przypadków użycia dla tego typu. W następnych sekcjach opisujemy uprawnienia, które musisz zadeklarować, wymagania w czasie działania oraz przypadki użycia każdego typu.
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.Uwaga: uprawnienie czasu działania
CAMERA
podlega ograniczeniom podczas używania. Z tego powodu nie możesz utworzyć usługi na pierwszym planiecamera
, gdy aplikacja działa w tle, z pewnymi wyjątkami. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania.- 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 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:
Zadeklaruj w pliku manifestu co najmniej 1 z tych uprawnień:
Wymagane jest co najmniej 1 z tych uprawnień:
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 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
- 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.
Zdrowie
- 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
startForeground()
, FOREGROUND_SERVICE_TYPE_HEALTH
- Wymagania wstępne środowiska wykonawczego
Musi być spełniony co najmniej 1 z tych warunków:
Zadeklaruj uprawnienia
HIGH_SAMPLING_RATE_SENSORS
w pliku manifestu.Prześlij prośbę o co najmniej 1 z tych uprawnień do działania:
Uwaga: uprawnienie czasu działania
BODY_SENSORS
podlega ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyćhealth
usługi na pierwszym planie, która używa czujników na ciele, gdy aplikacja działa w tle (z kilkoma wyjątkami). 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:
Uwaga: aby sprawdzić, czy użytkownik włączył usługi lokalizacyjne i czy zezwolił na dostęp do uprawnień w czasie wykonywania aplikacji, użyj
PermissionChecker#checkSelfPermission()
.Uwaga: uprawnienia do korzystania z lokalizacji w czasie działania podlegają ograniczeniom podczas korzystania. 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łaniaACCESS_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 API geofence.
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
- Ciągłe odtwarzanie 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.
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 wartość przekazywana do
startForeground()
, FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Wymagania wstępne środowiska wykonawczego
Przed uruchomieniem usługi na pierwszym planie wywołaj metodę
createScreenCaptureIntent()
. W ten sposób wyświetli się powiadomienie o uprawnieniach. Użytkownik musi przyznać uprawnienia, zanim będzie można utworzyć usługę.Po utworzeniu usługi na pierwszym planie możesz wywołać funkcję
MediaProjectionManager.getMediaProjection()
.- Opis
Wyświetlanie treści na wyświetlaczu innym niż główny lub urządzeniu zewnętrznym przy użyciu interfejsów
MediaProjection
API. Te treści nie muszą być wyłącznie treściami multimedialnymi.- Alternatywy
Aby przesyłać strumieniowo multimedia na inne urządzenie, użyj pakietu SDK Google Cast.
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 uprawnienia czasu działania
RECORD_AUDIO
i uzyskaj je.Uwaga: uprawnienie czasu działania
RECORD_AUDIO
podlega ograniczeniom podczas używania. Z tego powodu nie możesz utworzyć usługi na pierwszym planiemicrophone
, gdy aplikacja działa w tle, z pewnymi wyjątkami. Więcej informacji znajdziesz w artykule Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania.- Opis
Kontynuowanie rejestrowania dźwięku przez mikrofon w tle, np. w nagrywarkach głosowych lub aplikacjach 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 wartość przekazywana do
startForeground()
, FOREGROUND_SERVICE_TYPE_PHONE_CALL
- Wymagania wstępne środowiska wykonawczego
Musi być spełniony co najmniej 1 z tych warunków:
- Aplikacja zadeklarowała uprawnienia
MANAGE_OWN_CALLS
w pliku manifestu.
- Aplikacja zadeklarowała uprawnienia
- Aplikacja jest domyślną aplikacją do wybierania numerów w ramach roli
ROLE_DIALER
.
- Aplikacja jest domyślną aplikacją do wybierania numerów w ramach roli
- Opis
Kontynuowanie trwającego połączenia za pomocą interfejsów API
ConnectionService
.- 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 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ótkie usługi
- 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()
lubService.stopForeground()
przed przekroczeniem limitu czasu. W przeciwnym razie wywoływana jest nowa funkcjaService.onTimeout()
, która daje aplikacjom krótką możliwość wywołania funkcjistopSelf()
lubstopForeground()
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ę oFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. Z tych powodów sprawdzoną metodą jest implementowanie funkcjiService.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 zwrotnegoService.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 parametremFOREGROUND_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łądForegroundServiceStartNotAllowedException
.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ę typushortService
. 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_USE
typu 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ć 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 sekcji
android:foregroundServiceType
systemExempted
- Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
- stała wartość przekazywana do
startForeground()
, FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
- Wymagania wstępne środowiska wykonawczego
- Brak
- Opis
Zarezerwowane dla aplikacji systemowych i określonych integracji systemowych, aby nadal używać usług na pierwszym planie.
Aby korzystać z tego typu reklam, aplikacja musi spełniać co najmniej 1 z tych kryteriów:
- Urządzenie jest w stanie trybu demonstracyjnego
- Aplikacja jest Właścicielem urządzenia
- Aplikacja jest właścicielem narzędzia Profiler
- Aplikacje Bezpieczeństwo z rolą
ROLE_EMERGENCY
- Aplikacje administratora urządzenia
- Aplikacje, które mają uprawnienia
SCHEDULE_EXACT_ALARM
lubUSE_EXACT_ALARM
i korzystają z usługi na pierwszym planie, aby kontynuować alarmy w tle, w tym alarmy tylko z wibracją. Aplikacje VPN (skonfigurowane za pomocą Ustawienia > Sieć i internet > VPN)
W przeciwnym razie deklaracja tego typu spowoduje, że system zgłosi błąd
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 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.