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

Począwszy od Androida 14 (poziom interfejsu API 34) dla każdej usługi na pierwszym planie musisz zadeklarować odpowiedni typ usługi. Oznacza to, że musisz zadeklarować typ usługi w manifeście aplikacji, a także poprosić o odpowiednie uprawnienie usługi na pierwszym planie dla tego typu (a nie tylko poprosić o uprawnienie FOREGROUND_SERVICE). Ponadto w zależności od typu usługi na pierwszym planie przed jej uruchomieniem konieczne może być poproszenie o uprawnienia w czasie działania.

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ługi camera 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:

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

Utwórz zadania przenoszenia danych inicjowane przez użytkownika, aby umożliwić użytkownikom rozpoczęcie długotrwałych zadań przesyłania lub pobierania danych.

Użyj interfejsu API menedżera pobierania, aby pobrać dane z identyfikatora URI.

Użyj aplikacji BackupManager, aby utworzyć kopię zapasową lub przywrócić dane.

W przypadku innych zastosowań skorzystaj z usługi WorkManager.

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:

Uwaga: uprawnienia środowiska wykonawczego BODY_SENSORS podlegają ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyć usługi na pierwszym planie health, 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 domenie
android:foregroundServiceType
location
Uprawnienia do zadeklarowania w pliku manifestu
FOREGROUND_SERVICE_LOCATION
Stała do przekazywania do: startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Wymagania wstępne środowiska wykonawczego

Poproś o przyznanie co najmniej jednego z tych uprawnień w czasie działania:

Uwaga: dostęp do lokalizacji w czasie działania podlega ograniczeniom podczas korzystania. Z tego powodu nie możesz utworzyć usługi location 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

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

Alternatywy

Jeśli aplikacja musi być aktywowana, 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 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ługi microphone 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 jest domyślną aplikacją telefonu w roli ROLE_DIALER.
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() lub Service.stopForeground() przed upływem limitu czasu. W przeciwnym razie wywoływany jest nowy Service.onTimeout(), co daje aplikacjom krótką okazję do wywołania metody stopSelf() lub stopForeground() 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 elemencie FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Dlatego wdrożenie wywołania zwrotnego Service.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 zwrotnego Service.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 parametrem FOREGROUND_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łanie ForegroundServiceStartNotAllowedException.

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ę typu shortService. 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ć 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>

System wykluczony

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:

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.