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

Aby pomóc deweloperom w bardziej świadomym definiowaniu rozwiązań z myślą o użytkownikach na pierwszym planie usług, w Androidzie 10 wprowadzono android:foregroundServiceType w elemencie <service>.

Jeśli aplikacja jest kierowana na Androida 14, musi określić odpowiednią usługę na pierwszym planie . Podobnie jak w poprzednich wersjach Androida, można łączyć wiele typów. Ten zawiera listę typów usług na pierwszym planie do wyboru:

• camera
• connectedDevice
• dataSync
• health
• location
• mediaPlayback
• mediaProjection
• microphone
• phoneCall
• remoteMessaging
• shortService
• specialUse
• systemExempted

Jeśli przypadek użycia w Twojej aplikacji nie jest powiązany z żadnym z tych typów, zalecamy przeprowadzenie migracji logiki do WorkManagera lub zadań przenoszenia danych inicjowanych przez użytkownika.

health, remoteMessaging, shortService, specialUse i systemExempted są nowością w Androidzie 14.

Poniższy fragment kodu zawiera przykładową usługę 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 ma zdefiniowanych typów dla danej usługi w pliku manifestu, system podniesie MissingForegroundServiceTypeException po wywołaniu usługi startForeground().

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, które wprowadza (w zależności od typu tej usługi). Te uprawnienia znajdują się w sekcjach oznaczonych jako „Uprawnienia, które musisz zadeklarować w pliku manifestu” w sekcji Zamierzone zastosowania i egzekwowanie poszczególnych typów usług 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

Sprawdzoną metodą w przypadku aplikacji uruchamiających usługi na pierwszym planie jest użycie Wersja startForeground() na ServiceCompat (dostępna na Androidax Core 1.12 i wyższych), w którym przekazywana jest sekwencja bitowa. liczba całkowita typów usług na pierwszym planie. Możesz przekazać jeden lub więcej typów danych, .

Zazwyczaj należy zadeklarować tylko typy wymagane w konkretnym przypadku użycia. Ułatwia to spełnienie oczekiwań systemu w odniesieniu do każdego pierwszego planu. Jeśli usługa na pierwszym planie jest uruchamiana z kilkoma typami, usługa na pierwszym planie musi być zgodna z egzekwowaniem zasad przez platformę wymagania 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 jest określony typ do wartości zdefiniowanych w pliku manifestu. Jeśli usługa nie została określona w pliku manifestu, system zgłasza MissingForegroundServiceTypeException

Jeśli po uruchomieniu usługa na pierwszym planie wymaga nowych uprawnień, należy ponownie wywołać metodę startForeground() i dodać nowe typy usług. Dla: Załóżmy, że aplikacja do fitnessu korzysta z usługi trackera do biegania, która zawsze wymaga informacje o dokumencie location, ale mogą, ale nie muszą, być wymagane uprawnienia media. Ty będzie musiał zadeklarować w pliku manifestu 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. Jeśli użytkownik chce rozpocząć odtwarzanie dźwięku, zadzwoń ponownie do użytkownika startForeground() i przekaż location|mediaPlayback

Sprawdzanie czasu działania systemu

System sprawdza, czy dany rodzaj usług na pierwszym planie jest używany, i potwierdza, czy aplikacja żąda odpowiednich uprawnień w czasie działania lub korzysta z wymaganych interfejsów API. Na przykład system oczekuje, że aplikacje korzystające z usługi na pierwszym planie typu FOREGROUND_SERVICE_TYPE_LOCATION będą wysyłać żądania ACCESS_COARSE_LOCATION lub ACCESS_FINE_LOCATION.

Oznacza to, że gdy żądają od użytkownika uprawnień i uruchamiają usługi na pierwszym planie, aplikacje muszą wykonać określoną kolejność działań. Należy poprosić o uprawnienia i przyznać je przed próbą wywołania przez aplikację startForeground(). Aplikacje, które proszą o odpowiednie uprawnienia po uruchomieniu usługi na pierwszym planie, muszą zmienić tę kolejność działań i poprosić o odpowiednie uprawnienia przed uruchomieniem tej usługi.

Szczegółowe informacje o egzekwowaniu zasad na platformie znajdziesz w sekcji „Wymagania dotyczące środowiska wykonawczego” w sekcji o zamierzonych przypadkach użycia i ich egzekwowaniu w przypadku poszczególnych typów usług 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ć konkretne uprawnienie w pliku manifestu, spełnić określone wymagania w czasie działania, a aplikacja musi spełniać jeden z zamierzonych dla niego zestawów przypadków użycia. W sekcjach poniżej znajdziesz informacje o uprawnieniach, które musisz zadeklarować, o wymaganiach wstępnych dotyczących środowiska wykonawczego oraz o zamierzonych przypadkach użycia poszczególnych typów.

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:

• Zadeklaruj w pliku manifestu co najmniej jedno z tych uprawnień:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

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

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

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

Więcej informacji znajdziesz w artykule Alternatywy dla usług działających na pierwszym planie do synchronizacji danych.

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:

• Zadeklaruj uprawnienie HIGH_SAMPLING_RATE_SENSORS w pliku manifestu.

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

  • BODY_SENSORS
  • ACTIVITY_RECOGNITION

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

android:foregroundServiceType

location

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_LOCATION

Stała przekazu do startForeground()

FOREGROUND_SERVICE_TYPE_LOCATION

Wymagania wstępne środowiska wykonawczego

Użytkownik musi mieć włączone usługi lokalizacyjne, a aplikacji musi przyznać co najmniej jedno z tych uprawnień w czasie działania aplikacji:

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION

Uwaga: aby sprawdzić, czy użytkownik włączył usługi lokalizacyjne i czy przyznał dostęp do uprawnień czasu działania, użyj funkcji PermissionChecker#checkSelfPermission().

Uwaga: uprawnienia czasu działania lokalizacji podlegają ograniczeniom podczas używania. Z tego powodu nie możesz utworzyć usługi na pierwszym planie location, gdy aplikacja działa w tle, chyba że otrzymasz uprawnienie ACCESS_BACKGROUND_LOCATION w czasie działania. Więcej informacji znajdziesz w artykule o ograniczeniach uruchamiania usług działających na pierwszym planie, które wymagają uprawnień podczas używania.

Opis

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

Alternatywy

Jeśli Twoja aplikacja musi być aktywowana, gdy użytkownik dotrze do określonej lokalizacji, rozważ użycie interfejsu API geofence.

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

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

android:foregroundServiceType

systemExempted

Uprawnienia do zadeklarowania w pliku manifestu

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Stała przekazu do startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Wymagania wstępne środowiska wykonawczego

Brak

Opis

Zarezerwowana dla aplikacji systemowych i określonych integracji systemów, aby nadal korzystać z usług na pierwszym planie.

Aby korzystać z tego typu, aplikacja musi spełniać co najmniej jedno z tych kryteriów:

• Urządzenie działa w trybie demonstracyjnym
• Aplikacja jest właścicielem urządzenia.
• Aplikacja jest właścicielem profilu
• Aplikacje związane z bezpieczeństwem, które mają rolę ROLE_EMERGENCY
• aplikacje Administrator urządzenia,
• aplikacje obsługujące SCHEDULE_EXACT_ALARM lub USE_EXACT_ALARM, użytkownik: , usługa na pierwszym planie, aby kontynuowała alarmy w tle, w tym alarmy tylko z czujnikiem haptycznym.

• aplikacje VPN (konfigurowane za pomocą Ustawienia > Sieć i internet > VPN);

  W przeciwnym razie zadeklarowanie tego typu powoduje, że system przekazuje 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 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.