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 korzysta z zasobów systemu.

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 zawierać 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 opisujemy, jakie uprawnienia są wymagane do korzystania z usług działających na pierwszym planie oraz jak uruchomić taką usługę i usunąć ją z tle. Zawiera ona też informacje o tym, jak powiązać określone przypadki użycia z typami usług na pierwszym planie, oraz o ograniczeniach dostępu, które wchodzą w życie, gdy uruchomisz usługę na pierwszym planie z aplikacji działającej w tle.

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

Od Androida 13 (poziom interfejsu API 33) użytkownicy mogą domyślnie zamykać powiadomienia powiązane z usługą 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:

W Androidzie 13 (API na poziomie 33) lub nowszym, jeśli użytkownik odmówi wydania uprawnienia do powiadomień, nadal będzie widzieć powiadomienia dotyczące usług na pierwszym planie w Menedżerze zadań, ale nie będzie ich widzieć w szufladzie 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 zadeklarować rodzaj wykonywanej pracy.

Jeśli na przykład Twoja aplikacja tworzy usługę na pierwszym planie, która odtwarza muzykę, możesz zadeklarować ją 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 kierowane na Androida 9 (poziom interfejsu API 28) lub nowszego i korzystające z usług działających na pierwszym planie muszą żądać parametru FOREGROUND_SERVICE w manifeście aplikacji, jak pokazano w tym fragmencie kodu. Jest to normalne uprawnienie, więc system automatycznie przyznaje je aplikacji, która o nie prosi.

Dodatkowo, jeśli aplikacja jest kierowana na interfejs API na poziomie 34 lub wyższym, musi żądać odpowiedniego typu uprawnień do rodzaju pracy wykonywanej przez usługę na pierwszym planie. Każdy typ usługi na pierwszym planie ma odpowiedni typ uprawnień. 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ę na pierwszym planie typu location, system sprawdzi, czy Twoja 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.

Uruchom usługę 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). Ta metoda przyjmuje 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 należy usunąć także powiadomienie na pasku stanu. Pamiętaj, że usługa będzie nadal działać.

Jeśli zatrzymasz usługę, gdy działa na pierwszym planie, 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 działających obecnie w tle. Gdy naciśniesz ten przycisk, pojawi się okno z listą nazw 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 ma etykietę 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.
  • Odtwarzanie multimediów zostanie zatrzymane.
  • Powiadomienie powiązane z usługą na pierwszym planie zostanie usunięte.
  • Aplikacja pozostanie w historii.
  • Zaplanowane zadania są wykonywane w wyznaczonym czasie.
  • Alarmy włączają się o zaplanowanym czasie lub w określonym przedziale czasowym.

Aby sprawdzić, czy aplikacja działa zgodnie z oczekiwaniami, gdy użytkownik ją zatrzymuje i po jej zatrzymaniu, uruchom to polecenie ADB w oknie terminala:

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.

Wykluczenia dotyczą poszczególnych 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 aplikacje z tych typów uruchamiają usługę na pierwszym planie, są widoczne w Menedżerze zadań, ale obok nazwy aplikacji nie ma przycisku Zatrzymaj, który użytkownik mógłby 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. Specjalistyczne interfejsy API często dają dodatkowe możliwości specyficzne dla danego przypadku użycia, które w innym przypadku należałoby opracować samodzielnie. Na przykład interfejs Bubbles API obsługuje złożoną logikę interfejsu użytkownika w przypadku aplikacji do obsługi wiadomości, które muszą implementować funkcje okienka czatu.

Dokumentacja dotycząca typów usług na pierwszym planie zawiera listę odpowiednich alternatyw dla usług na pierwszym planie.

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 tych uprawnień, system zgłasza SecurityException.

W przypadku uprawnień do korzystania z usług może to spowodować problem. Jeśli aplikacja ma uprawnienia „podczas używania”, ma je tylko podczas działania 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ę medyczną, która wymaga uprawnienia BODY_SENSORS, a aplikacja nie ma tego uprawnienia, system zgłasza wyjątek. (Nie dotyczy to placówek ochrony zdrowia, które wymagają różnych uprawnień, np. ACTIVITY_RECOGNITION). Połączenie PermissionChecker.checkSelfPermission() nie zapobiega 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”.

Jeśli więc usługa na pierwszym planie potrzebuje uprawnienia „podczas używania”, musisz wywołać funkcję Context.startForegroundService() lub Context.bindService(), gdy aplikacja ma widoczną aktywność, chyba że usługa kwalifikuje się do jednej z określonych 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.
  • Działanie usługi 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 ograniczyła dostęp do lokalizacji, mikrofonu i aparatu, w logcat pojawi się ten komunikat:

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