Wymagane są typy usług działających na pierwszym planie

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 czasie wykonywania

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass location|mediaPlayback.

Sprawdzanie systemu w czasie działania

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.

Zastosowania i sposoby egzekwowania 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.

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:

Uwaga: uprawnienia do odczytu BODY_SENSORS i uprawnienia do odczytu na podstawie czujników są ograniczone w czasie działania. Z tego powodu nie możesz utworzyć usługi health na pierwszym planie, która używa czujników ciała, gdy aplikacja działa w tle, chyba że masz przyznane uprawnienia BODY_SENSORS_BACKGROUND (poziom interfejsu API 33–35) lub READ_HEALTH_DATA_IN_BACKGROUND (poziom interfejsu API 36 lub nowszy). 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ł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

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

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service 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

Continue microphone capture from the background, such as voice recorders or communication apps.

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ótka usługa

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 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_USEtypu 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ć 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

Foreground service type to declare in manifest under
android:foregroundServiceType
systemExempted
Permission to declare in your manifest
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Runtime prerequisites
None
Description

Reserved for system applications and specific system integrations, to continue to use foreground services.

To use this type, an app must meet at least one of the following criteria:

  • Device is in demo mode state
  • App is a Device Owner
  • App is a Profiler Owner
  • Safety Apps that have the ROLE_EMERGENCY role
  • Device Admin apps
  • Apps holding SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM permission and are using Foreground Service to continue alarms in the background, including haptics-only alarms.

  • VPN apps (configured using Settings > Network & Internet > VPN)

    Otherwise, declaring this type causes the system to throw a ForegroundServiceTypeNotAllowedException.

Egzekwowanie zasad Google Play w przypadku korzystania z 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.