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

如果以 Android 14 为目标平台的应用使用前台服务，则必须根据前台服务类型声明 Android 14 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。

所有这些权限都定义为一般权限，并默认授予。用户无法撤消这些权限。

Uwzględnij typ usługi na pierwszym planie w czasie wykonywania

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

为了使用给定的前台服务类型，您必须在清单文件中声明特定权限，必须满足特定的运行时要求，并且应用必须满足该类型的其中一组预期用例。以下部分介绍了您必须声明的权限、运行时前提条件以及每种类型的预期用例。

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

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:

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.

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

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 przyznanie uprawnień czasu działania RECORD_AUDIO.

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

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

要在清单中声明的前台服务类型
android:foregroundServiceType
specialUse
在清单中声明的权限
FOREGROUND_SERVICE_SPECIAL_USE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
运行时前提条件
无
说明

涵盖其他前台服务类型未涵盖的所有有效前台服务用例。

除了声明 FOREGROUND_SERVICE_TYPE_SPECIAL_USE 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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 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 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.