Usługi działające na pierwszym planie

Usługi działające na pierwszym planie wykonują operacje zauważalne dla użytkownika.

Usługi na pierwszym planie wyświetlają powiadomienie na pasku stanu, aby poinformować użytkowników, że aplikacja wykonuje zadanie na pierwszym planie i zużywa zasoby systemowe.

Przykłady aplikacji, które korzystają z usług na pierwszym planie:

  • Aplikacja odtwarzająca muzykę, która działa na pierwszym planie. Powiadomienie może wyświetlać aktualnie odtwarzany utwór.
  • Aplikacja fitness, która rejestruje bieg użytkownika w usłudze na pierwszym planie, po otrzymaniu zgody użytkownika. Powiadomienie może zawierać informację o przebytej przez użytkownika odległości podczas bieżącej sesji fitness.

Usługi na pierwszym planie używaj tylko wtedy, gdy aplikacja musi wykonać zadanie, które jest zauważalne dla użytkownika, nawet gdy nie wchodzi on z nią w bezpośrednią interakcję. Jeśli działanie jest na tyle mało istotne, że chcesz użyć powiadomienia o minimalnym priorytecie, utwórz zamiast tego zadania działającego w tle.

W tym dokumencie znajdziesz opis wymaganych uprawnień do korzystania z usług na pierwszym planie oraz informacje o tym, jak uruchomić taką usługę i usunąć ją z tła. Opisuje on również sposób powiązania określonych przypadków użycia z typami usług działających na pierwszym planie oraz ograniczenia dostępu obowiązujące po uruchomieniu takiej usługi z poziomu aplikacji, która działa w tle.

Użytkownik może domyślnie zamknąć powiadomienie

Począwszy od Androida 13 (poziom interfejsu API 33) użytkownicy mogą domyślnie odrzucać powiadomienia powiązane z usługami na pierwszym planie. Aby to zrobić, użytkownicy muszą przesunąć palcem po powiadomieniu. Zazwyczaj powiadomienie nie znika, dopóki usługa na pierwszym planie nie zostanie zatrzymana lub usunięta z pierwszego planu.

Jeśli chcesz, aby powiadomienie nie mogło zostać zamknięte przez użytkownika, przekaż parametr true do metody setOngoing() podczas tworzenia powiadomienia za pomocą funkcji Notification.Builder.

Usługi, które wyświetlają powiadomienie natychmiast

Jeśli usługa na pierwszym planie ma co najmniej jedną z tych cech, system wyświetla powiązane powiadomienie natychmiast po uruchomieniu usługi, nawet na urządzeniach z Androidem 12 lub nowszym:

Jeśli użytkownik odmówi przyznania uprawnień na powiadomienia na Androidzie 13 (poziom interfejsu API 33) lub nowszym, w Menedżerze zadań będzie nadal widzieć powiadomienia związane z usługami działającymi na pierwszym planie, ale nie będą widoczne w panelu powiadomień.

Deklarowanie usług na pierwszym planie w pliku manifestu

W pliku manifestu aplikacji zadeklaruj każdą usługę na pierwszym planie za pomocą elementu <service>. W przypadku każdej usługi użyj atrybutu android:foregroundServiceType, aby określić, jakie zadania wykonuje usługa.

Jeśli na przykład aplikacja tworzy usługę na pierwszym planie, która odtwarza muzykę, możesz zadeklarować tę usługę w ten sposób:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
  <application ...>

    <service
        android:name=".MyMediaPlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="false">
    </service>
  </application>
</manifest>

Jeśli do usługi stosuje się kilka typów, rozdziel je operatorem |. Na przykład usługa, która korzysta z kamery i mikrofonu, mogłaby być zadeklarowana w ten sposób:

android:foregroundServiceType="camera|microphone"

Proś o uprawnienia usługi działającej na pierwszym planie

Aplikacje przeznaczone na Androida 9 (poziom interfejsu API 28) lub nowszego, które korzystają z usług na pierwszym planie, muszą w pliku manifestu aplikacji poprosić o FOREGROUND_SERVICE, jak pokazano w tym fragmencie kodu. Jest to normalne uprawnienie, więc system automatycznie przyznaje je aplikacji, która o nie prosi.

Jeśli aplikacja jest kierowana na interfejs API na poziomie 34 lub wyższym, musi poprosić o odpowiednie uprawnienia do wykonywania zadań przez usługę na pierwszym planie. Każdy typ usługi na pierwszym planie ma odpowiadający mu typ uprawnienia. Jeśli na przykład aplikacja uruchamia usługę na pierwszym planie, która korzysta z aparatu, musisz poprosić o uprawnienia FOREGROUND_SERVICE i FOREGROUND_SERVICE_CAMERA. To są wszystkie zwykłe uprawnienia, więc system przyznaje je automatycznie, jeśli są wymienione w pliku manifestu.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA"/>

    <application ...>
        ...
    </application>
</manifest>

Wymagania wstępne usługi działającej na pierwszym planie

Od Androida 14 (poziom interfejsu API 34) podczas uruchamiania usługi na pierwszym planie system sprawdza określone wymagania wstępne w zależności od typu usługi. Jeśli na przykład spróbujesz uruchomić usługę działającą na pierwszym planie typu location, system sprawdzi, czy aplikacja ma już uprawnienie ACCESS_COARSE_LOCATION lub ACCESS_FINE_LOCATION. Jeśli nie, system zgłosi błądSecurityException.

Dlatego przed uruchomieniem usługi na pierwszym planie musisz sprawdzić, czy są spełnione wymagania wstępne. Dokumentacja typu usługi na pierwszym planie zawiera wymagane warunki wstępne dla każdego typu usługi na pierwszym planie.

Uruchamianie usługi na pierwszym planie

Zanim poprosisz system o uruchomienie usługi jako usługi na pierwszym planie, uruchom tę usługę:

Kotlin

val intent = Intent(...) // Build the intent for the service
context.startForegroundService(intent)

Java

Context context = getApplicationContext();
Intent intent = new Intent(...); // Build the intent for the service
context.startForegroundService(intent);

W usłudze, zwykle w funkcji onStartCommand(), możesz poprosić o uruchomienie usługi na pierwszym planie. Aby to zrobić, wywołaj ServiceCompat.startForeground() (funkcja dostępna w Androidziex Core 1.12 lub nowszym). Przyjmuje ona te parametry:

Te typy mogą być podzbiorem typów zadeklarowanych w pliku manifestu, w zależności od konkretnego przypadku użycia. Jeśli chcesz dodać więcej typów usług, możesz ponownie zadzwonić do startForeground().

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 odtwarzać multimediów. W pliku manifestu musisz zadeklarować zarówno location, jak i mediaPlayback. Jeśli użytkownik rozpocznie uruchomienie i chce tylko śledzić swoją lokalizację, aplikacja powinna wywołać metodę startForeground() i przekazać tylko uprawnienie ACCESS_FINE_LOCATION. Następnie, jeśli użytkownik chce zacząć odtwarzać dźwięk, wywołaj ponownie startForeground() i przekaż bitową kombinację wszystkich typów usług na pierwszym planie (w tym przypadku ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK).

Oto przykład uruchamiania usługi na pierwszym planie aparatu:

Kotlin

class MyCameraService: Service() {

  private fun startForeground() {
    // Before starting the service as foreground check that the app has the
    // appropriate runtime permissions. In this case, verify that the user has
    // granted the CAMERA permission.
    val cameraPermission =
            PermissionChecker.checkSelfPermission(this, Manifest.permission.CAMERA)
    if (cameraPermission != PermissionChecker.PERMISSION_GRANTED) {
        // Without camera permissions the service cannot run in the foreground
        // Consider informing user or updating your app UI if visible.
        stopSelf()
        return
    }

    try {
        val notification = NotificationCompat.Builder(this, "CHANNEL_ID")
            // Create the notification to display while the service is running
            .build()
        ServiceCompat.startForeground(
            /* service = */ this,
            /* id = */ 100, // Cannot be 0
            /* notification = */ notification,
            /* foregroundServiceType = */
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA
            } else {
                0
            },
        )
    } catch (e: Exception) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
                && e is ForegroundServiceStartNotAllowedException) {
            // App not in a valid state to start foreground service
            // (e.g. started from bg)
        }
        // ...
    }
  }
}

Java

public class MyCameraService extends Service {

    private void startForeground() {
        // Before starting the service as foreground check that the app has the
        // appropriate runtime permissions. In this case, verify that the user
        // has granted the CAMERA permission.
        int cameraPermission =
            ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA);
        if (cameraPermission == PackageManager.PERMISSION_DENIED) {
            // Without camera permissions the service cannot run in the
            // foreground. Consider informing user or updating your app UI if
            // visible.
            stopSelf();
            return;
        }

        try {
            Notification notification =
                new NotificationCompat.Builder(this, "CHANNEL_ID")
                    // Create the notification to display while the service
                    // is running
                    .build();
            int type = 0;
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
                type = ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
            }
            ServiceCompat.startForeground(
                    /* service = */ this,
                    /* id = */ 100, // Cannot be 0
                    /* notification = */ notification,
                    /* foregroundServiceType = */ type
            );
        } catch (Exception e) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S &&
                    e instanceof ForegroundServiceStartNotAllowedException
            ) {
                // App not in a valid state to start foreground service
                // (e.g started from bg)
            }
            // ...
        }
    }

    //...
}

Usuwanie usługi z pierwszego planu

Aby usunąć usługę z pierwszego planu, wywołaj stopForeground(). Ta metoda przyjmuje wartość logiczną, która wskazuje, czy usunąć też powiadomienie na pasku stanu. Pamiętaj, że usługa nadal działa.

Jeśli usługa jest uruchomiona na pierwszym planie, a Ty ją zatrzymasz, powiadomienie o niej zostanie usunięte.

Obsługa zatrzymywania przez użytkownika aplikacji uruchamiających usługi na pierwszym planie

U dołu panelu powiadomień znajduje się przycisk wskazujący liczbę aplikacji, które są obecnie uruchomione w tle. Po naciśnięciu tego przycisku pojawi się okno z nazwami różnych aplikacji. przycisk Zatrzymaj po prawej stronie każdej aplikacji;
Rysunek 1. Zarządzanie zadaniami na urządzeniach z Androidem w wersji 13 lub nowszej.

Od Androida 13 (poziom interfejsu API 33) użytkownicy mogą kończyć procesy w schowku powiadomień, aby zatrzymać aplikację, która ma aktywne usługi na pierwszym planie, niezależnie od wersji docelowego pakietu SDK tej aplikacji. Ta funkcja, zwana Menedżerem zadań, wyświetla listę aplikacji, które obecnie uruchamiają usługę na pierwszym planie.

Ta lista jest oznaczona jako Aktywne aplikacje. Obok każdej aplikacji znajduje się przycisk Zatrzymaj. Rysunek 1 przedstawia proces zarządzania zadaniami na urządzeniu z Androidem 13.

Gdy użytkownik naciśnie przycisk Zatrzymaj obok aplikacji w Menedżerze zadań, nastąpią następujące działania:

  • System usunie aplikację z pamięci. W rezultacie cała aplikacja się zatrzymuje, a nie tylko uruchomiona usługa na pierwszym planie.
  • System usuwa z aplikacji stos aktywności.
  • Zatrzymuje się odtwarzanie multimediów.
  • Powiadomienie powiązane z usługą na pierwszym planie zostanie usunięte.
  • Aplikacja pozostaje w historii.
  • Zaplanowane zadania są wykonywane o zaplanowanej godzinie.
  • Alarmy włączają się o zaplanowanym czasie lub w określonym przedziale czasowym.

Aby sprawdzić, czy aplikacja zachowuje się zgodnie z oczekiwaniami, gdy użytkownik ją zatrzymuje, uruchom w oknie terminala to polecenie ADB:

adb shell cmd activity stop-app PACKAGE_NAME

Wyjątki

System przewiduje kilka poziomów wyjątków w przypadku niektórych typów aplikacji, co jest opisane w następnych sekcjach.

Wyjątki dotyczą aplikacji, a nie procesów. Jeśli system zwalnia z ochrony jeden proces w aplikacji, zwalnia z ochrony wszystkie procesy w tej aplikacji.

Wyjątki dotyczące wyświetlania w Menedżerze zadań

Poniższe aplikacje mogą uruchamiać usługę na pierwszym planie i w ogóle nie wyświetlać się w Menedżerze zadań:

Wyjątki od możliwości zatrzymania przez użytkowników

Gdy na pierwszym planie działają te typy aplikacji, pojawiają się w Menedżerze zadań, ale obok nazwy aplikacji nie ma przycisku Zatrzymaj, który użytkownik może kliknąć:

Zamiast usług na pierwszym planie używaj interfejsów API do określonych celów

W przypadku wielu zastosowań istnieją interfejsy API platformy lub Jetpacka, których możesz używać do wykonywania zadań, do których w przeciwnym razie używałbyś usługi na pierwszym planie. Jeśli istnieje odpowiedni interfejs API, który został stworzony do określonego celu, prawie zawsze należy z niego korzystać zamiast usługi na pierwszym planie. Specjalnie zaprojektowane interfejsy API często zapewniają dodatkowe funkcje, które w przeciwnym razie musiałbyś tworzyć samodzielnie. Na przykład interfejs Bubbles API obsługuje złożoną logikę UI w aplikacjach do obsługi wiadomości, które muszą zaimplementować funkcje dymków czatu.

Dokumentacja typów usług działających na pierwszym planie zawiera listę dobrych alternatywnych rozwiązań.

Ograniczenia dotyczące uruchamiania usługi na pierwszym planie w tle

Aplikacje kierowane na Androida 12 lub nowszego nie mogą uruchamiać usług na pierwszym planie, gdy aplikacja działa w tle, z wyjątkiem kilku szczególnych przypadków. Jeśli aplikacja próbuje uruchomić usługę na pierwszym planie, gdy sama działa w tle, a usługa na pierwszym planie nie spełnia jednego z wyjątków, system zgłasza błąd ForegroundServiceStartNotAllowedException.

Jeśli aplikacja chce uruchomić usługę na pierwszym planie, która wymaga uprawnień w trakcie korzystania (np. uprawnień do korzystania z ciała, aparatu, mikrofonu lub lokalizacji), nie może tworzyć tej usługi, gdy działa w tle, nawet jeśli kwalifikuje się do jednej z wyjątków od ograniczeń uruchamiania w tle. Wyjaśnienie tego powodu znajdziesz w sekcji Ograniczenia uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania.

Wykluczenia z ograniczeń uruchamiania w tle

W tych sytuacjach aplikacja może uruchamiać usługi na pierwszym planie, nawet gdy sama działa w tle:

Ograniczenia dotyczące uruchamiania usług na pierwszym planie, które wymagają uprawnień podczas korzystania

W Androidzie 14 (poziom API 34) lub nowszym występują specjalne sytuacje, o których musisz pamiętać, gdy uruchamiasz usługę na pierwszym planie, która wymaga uprawnień podczas korzystania.

Jeśli Twoja aplikacja jest kierowana na Androida 14 lub nowszą wersję, podczas tworzenia usługi na pierwszym planie system operacyjny sprawdza, czy aplikacja ma wszystkie odpowiednie uprawnienia dla tego typu usługi. Na przykład, gdy utworzysz usługę na pierwszym planie typu mikrofon, system operacyjny sprawdzi, czy Twoja aplikacja ma obecnie uprawnienie RECORD_AUDIO. Jeśli nie masz tego uprawnienia, system wyświetli komunikat SecurityException.

W przypadku uprawnień do korzystania z usług może to spowodować problem. Jeśli aplikacja ma uprawnienie podczas używania, ma je tylko na pierwszym planie. Oznacza to, że jeśli aplikacja działa w tle i próbuje utworzyć usługę działającą na pierwszym planie typu aparat, lokalizację lub mikrofon, system zauważy, że aplikacja obecnie nie ma wymaganych uprawnień i zwraca SecurityException.

Podobnie, jeśli aplikacja działa w tle i tworzy usługę ochrony zdrowia, która wymaga uprawnienia BODY_SENSORS, aplikacja nie ma obecnie tego uprawnienia, a system zgłasza wyjątek. (Nie dotyczy to usług medycznych, które wymagają innych uprawnień, takich jak ACTIVITY_RECOGNITION). Nawet wywołanie funkcji PermissionChecker.checkSelfPermission() nie nie zapobiegnie temu problemowi. Jeśli aplikacja ma uprawnienia podczas korzystania i wywołuje metodę checkSelfPermission(), aby sprawdzić, czy ma te uprawnienia, metoda zwraca PERMISSION_GRANTED, nawet jeśli aplikacja jest w tle. Jeśli metoda zwraca wartość PERMISSION_GRANTED, oznacza to, że „Twoja aplikacja ma to uprawnienie podczas używania aplikacji”.

Z tego powodu, jeśli usługa działająca na pierwszym planie wymaga uprawnień podczas używania, musisz wywołać metodę Context.startForegroundService() lub Context.bindService(), gdy w aplikacji występuje widoczna aktywność, chyba że usługa należy do jednego ze zdefiniowanych wyjątków.

Wyjątki od ograniczeń dotyczących uprawnień podczas korzystania

W niektórych sytuacjach nawet wtedy, gdy usługa na pierwszym planie jest uruchomiona, gdy aplikacja działa w tle, może ona nadal uzyskiwać informacje o lokalizacji, kamerze i mikrofonie, gdy aplikacja działa na pierwszym planie („podczas używania”).

W tych samych sytuacjach, jeśli usługa deklaruje typ usługi na pierwszym planie location i jest uruchamiana przez aplikację, która ma uprawnienie ACCESS_BACKGROUND_LOCATION, usługa ta może mieć dostęp do informacji o lokalizacji przez cały czas, nawet gdy aplikacja działa w tle.

Poniżej znajdziesz listę takich sytuacji:

  • Usługę uruchamia komponent systemu.
  • Usługa zaczyna się od interakcji z widżetami aplikacji.
  • Usługa rozpoczyna się od interakcji z powiadomieniem.
  • Usługa rozpoczyna się jako PendingIntent wysyłana z innej widocznej aplikacji.
  • Usługa uruchamia aplikację, która jest kontrolerem zasad urządzeń i działa w trybie właściciela urządzenia.
  • Usługa jest uruchamiana przez aplikację, która zapewnia VoiceInteractionService.
  • Usługa jest uruchamiana przez aplikację, która ma uprawnienia START_ACTIVITIES_FROM_BACKGROUND.
Określ, których usług dotyczy Twoja aplikacja

Podczas testowania aplikacji uruchom jej usługi działające na pierwszym planie. Jeśli uruchomiona usługa ma ograniczony dostęp do lokalizacji, mikrofonu i kamery, w Logcat pojawi się ten komunikat:

Foreground service started from background can not have \
location/camera/microphone access: service SERVICE_NAME