Typy usług działających na pierwszym planie są wymagane

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:

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 MissingForegroundServiceTypeExceptionpo 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

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

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 planie camera, 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

Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Runtime prerequisites

At least one of the following conditions must be true:

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

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

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

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ł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 API geofence.

Multimedia

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Runtime prerequisites
None
Description
Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
Alternatives
If you're showing picture-in-picture video, use Picture-in-Picture mode.

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 planie microphone, 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 jest domyślną aplikacją do wybierania numerów w ramach roli ROLE_DIALER.
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() 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
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. W tym celu określają element <property> w elemencie <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ć karty specialUse 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>

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:

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.