Службы переднего плана

Службы переднего плана выполняют операции, заметные пользователю.

Службы переднего плана отображают уведомление в строке состояния , чтобы пользователи знали, что ваше приложение выполняет задачу на переднем плане и потребляет системные ресурсы.

Примеры приложений, использующих службы переднего плана, включают следующее:

• Приложение музыкального проигрывателя, воспроизводящее музыку в службе переднего плана. В уведомлении может отображаться воспроизводимая в данный момент песня.
• Фитнес-приложение, которое записывает пробежку пользователя в службе переднего плана после получения разрешения от пользователя. В уведомлении может отображаться расстояние, которое пользователь преодолел во время текущей тренировки.

Используйте службу переднего плана только тогда, когда вашему приложению необходимо выполнить задачу, заметную для пользователя, даже если он не взаимодействует с приложением напрямую. Если действие имеет достаточно низкую важность и вы хотите использовать уведомление с минимальным приоритетом, вместо этого создайте фоновую задачу .

Примечание. Во многих случаях использования существует специально созданная платформа или API Jetpack, которые вы можете использовать для выполнения своей работы вместо службы переднего плана. Если такой API существует, почти всегда предпочтительнее использовать его вместо службы переднего плана. Дополнительные сведения см. в разделе Использование специальных API вместо служб переднего плана .

В этом документе описываются необходимые разрешения для использования служб переднего плана, а также способы запуска службы переднего плана и удаления ее из фона. Здесь также описывается, как связать определенные варианты использования с типами служб переднего плана, а также ограничения доступа, которые вступают в силу при запуске службы переднего плана из приложения, работающего в фоновом режиме.

Пользователь может отклонить уведомление по умолчанию

Начиная с Android 13 (уровень API 33), пользователи могут по умолчанию отклонять уведомления, связанные со службой переднего плана. Для этого пользователи проводят жестом по уведомлению. Традиционно уведомление не отклоняется до тех пор, пока служба переднего плана не будет остановлена ​​или удалена с переднего плана.

Если вы хотите, чтобы пользователь не мог отклонить уведомление, передайте true в метод setOngoing() при создании уведомления с помощью Notification.Builder .

Примечание. Устройства под управлением Android 12 (уровень API 31) или выше обеспечивают оптимизированную работу кратковременных служб переднего плана. На этих устройствах система ждет 10 секунд, прежде чем отобразить уведомление, связанное с приоритетной службой. Есть несколько исключений: некоторые типы сервисов всегда отображают уведомление немедленно .

Сервисы, которые сразу показывают уведомление

Если служба переднего плана имеет хотя бы одну из следующих характеристик, система отображает соответствующее уведомление сразу после запуска службы, даже на устройствах под управлением Android 12 или более поздней версии:

• Услуга связана с уведомлением, которое включает кнопки действий .
• Служба имеет foregroundServiceType mediaPlayback , mediaProjection или phoneCall .
• Служба предоставляет вариант использования, связанный с телефонными звонками, навигацией или воспроизведением мультимедиа, как определено в атрибуте категории уведомления.
• Служба отказалась от изменения поведения, передав FOREGROUND_SERVICE_IMMEDIATE в setForegroundServiceBehavior() при настройке уведомления.

В Android 13 (уровень API 33) или более поздней версии, если пользователь отказывает в разрешении на уведомление , он по-прежнему видит уведомления, связанные со службами переднего плана, в диспетчере задач , но не видит их в панели уведомлений.

Объявите службы переднего плана в своем манифесте

В манифесте вашего приложения объявите каждую из служб переднего плана вашего приложения с помощью элемента <service> . Для каждой службы используйте атрибут android:foregroundServiceType , чтобы указать, какую работу выполняет служба.

Важно! Все декларации приоритетных служб должны соответствовать требованиям Политики Google Play в отношении злоупотребления устройствами и сетями .

Например, если ваше приложение создает службу переднего плана, воспроизводящую музыку, вы можете объявить эту службу следующим образом:

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

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

Если к вашему сервису применимо несколько типов, разделите их | оператор. Например, служба, использующая камеру и микрофон, объявит об этом так:

android:foregroundServiceType="camera|microphone"

Примечание. В зависимости от уровня API, на который нацелено ваше приложение, вам может потребоваться объявить службы переднего плана в манифесте приложения:

• Уровень API 29 или выше: вы должны объявить все службы переднего плана, использующие информацию о местоположении, используя тип службы location .
• Уровень API 30 или выше: вы должны объявить все службы переднего плана, использующие камеру или микрофон, используя тип службы camera или microphone соответственно.
• Уровень API 34 или выше: вы должны объявить все службы переднего плана с их типами служб.

Если вы попытаетесь создать службу переднего плана, а ее тип не объявлен в манифесте, система выдаст MissingForegroundServiceTypeException при вызове startForeground() .

Даже если это не требуется, рекомендуется объявить все службы переднего плана и указать их типы служб.

Запросить разрешения службы переднего плана

Приложения, предназначенные для Android 9 (уровень API 28) или выше и использующие службы переднего плана, должны запрашивать FOREGROUND_SERVICE в манифесте приложения, как показано в следующем фрагменте кода. Это обычное разрешение , поэтому система автоматически предоставляет его запрашивающему приложению.

Кроме того, если приложение нацелено на уровень API 34 или выше, оно должно запросить соответствующий тип разрешения для типа работы, которую будет выполнять служба переднего плана. Каждому типу службы переднего плана соответствует соответствующий тип разрешения. Например, если приложение запускает службу переднего плана, использующую камеру, необходимо запросить разрешения FOREGROUND_SERVICE и FOREGROUND_SERVICE_CAMERA . Это все обычные разрешения, поэтому система предоставляет их автоматически, если они указаны в манифесте.

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

Примечание. Если приложение, ориентированное на уровень API 28 или выше, пытается создать службу переднего плана, не запрашивая разрешение FOREGROUND_SERVICE , система выдает SecurityException . Аналогично, если приложение нацелено на уровень API 34 или выше и не запрашивает соответствующее конкретное разрешение, система выдает SecurityException .

Предварительные условия службы переднего плана

Начиная с Android 14 (уровень API 34), при запуске службы переднего плана система проверяет наличие определенных предварительных условий в зависимости от типа службы. Например, если вы попытаетесь запустить приоритетную службу типа location , система проверит, имеет ли ваше приложение разрешение ACCESS_COARSE_LOCATION или ACCESS_FINE_LOCATION . Если этого не происходит, система выдает SecurityException .

По этой причине перед запуском приоритетной службы необходимо убедиться, что выполнены необходимые предварительные условия. В документации по типу службы переднего плана перечислены необходимые предварительные условия для каждого типа службы переднего плана.

Запуск службы переднего плана

Прежде чем вы запросите систему для запуска службы в качестве службы переднего плана, запустите саму службу:

Котлин

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

Ява

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

Внутри службы, обычно в onStartCommand() , вы можете запросить запуск службы на переднем плане. Для этого вызовите ServiceCompat.startForeground() (доступно в androidx-core 1.12 и выше). Этот метод принимает следующие параметры:

• Сервис
• Положительное целое число, которое однозначно идентифицирует уведомление в строке состояния.
• Сам объект Notification
• Типы служб переднего плана, определяющие работу, выполняемую службой.

Эти типы могут быть подмножеством типов, объявленных в манифесте , в зависимости от конкретного варианта использования. Затем, если вам нужно добавить дополнительные типы служб, вы можете снова вызвать startForeground() .

Примечание. Если вы передаете в startForeground тип службы переднего плана, который вы не объявили в манифесте, система выдает исключение IllegalArgumentException .

Например, предположим, что фитнес-приложение запускает службу отслеживания бега, которой всегда нужна информация location , но может потребоваться или не потребоваться воспроизведение мультимедиа. Вам нужно будет объявить location и mediaPlayback в манифесте. Если пользователь начинает прогон и просто хочет отслеживать свое местоположение, ваше приложение должно вызвать startForeground() и передать только разрешение ACCESS_FINE_LOCATION . Затем, если пользователь хочет начать воспроизведение звука, снова вызовите startForeground() и передайте побитовую комбинацию всех типов служб переднего плана (в данном случае ACCESS_FINE_LOCATION|FOREGROUND_SERVICE_MEDIA_PLAYBACK ).

Примечание. Уведомление в строке состояния должно иметь приоритет PRIORITY_LOW или выше. Если ваше приложение пытается использовать уведомление с более низким приоритетом, система добавляет сообщение в панель уведомлений, предупреждая пользователя об использовании приложением службы переднего плана.

Вот пример запуска службы переднего плана камеры:

Котлин

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)
        }
        // ...
    }
  }
}

Ява

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)
            }
            // ...
        }
    }

    //...
}

Удаление службы с переднего плана

Чтобы удалить службу с переднего плана, вызовите stopForeground() . Этот метод принимает логическое значение, которое указывает, следует ли также удалить уведомление в строке состояния. Обратите внимание, что служба продолжает работать.

Если вы остановите службу, пока она работает на переднем плане, ее уведомление будет удалено.

Обрабатывать инициируемую пользователем остановку приложений, запускающих службы переднего плана.

Рисунок 1. Рабочий процесс диспетчера задач на устройствах под управлением Android 13 или более поздней версии.

Начиная с Android 13 (уровень API 33), пользователи могут выполнить рабочий процесс из панели уведомлений , чтобы остановить приложение, в котором есть текущие службы переднего плана, независимо от целевой версии SDK этого приложения. Эта возможность, называемая Диспетчером задач , показывает список приложений, в которых в данный момент запущена служба приоритетного плана.

Этот список называется «Активные приложения» . Рядом с каждым приложением есть кнопка «Стоп» . На рис. 1 показан рабочий процесс диспетчера задач на устройстве под управлением Android 13.

Когда пользователь нажимает кнопку «Стоп» рядом с вашим приложением в диспетчере задач, происходят следующие действия:

• Система удалит ваше приложение из памяти. Таким образом, останавливается все ваше приложение , а не только работающая служба переднего плана.
• Система удаляет стек активности вашего приложения.
• Любое воспроизведение мультимедиа останавливается.
• Уведомление, связанное со службой переднего плана, удаляется.
• Ваше приложение останется в истории.
• Запланированные задания выполняются в запланированное время.
• Будильник сработает в запланированное время или временное окно.

Примечание. Система не отправляет вашему приложению обратные вызовы, когда пользователь нажимает кнопку «Стоп» . Когда ваше приложение начинает резервное копирование, полезно проверить причину REASON_USER_REQUESTED , которая является частью API ApplicationExitInfo .

Чтобы проверить, что ваше приложение ведет себя должным образом во время и после того, как пользователь останавливает ваше приложение, выполните следующую команду ADB в окне терминала:

adb shell cmd activity stop-app PACKAGE_NAME

Исключения

Система предоставляет несколько уровней исключений для определенных типов приложений, которые описаны в следующих разделах.

Исключения предоставляются для каждого приложения, а не для каждого процесса. Если система освобождает один процесс в приложении, все остальные процессы в этом приложении также освобождаются.

Примечание. Некоторые предустановленные приложения, настроенные производителем, также могут быть освобождены от налога.

Исключения из появления в Диспетчере задач вообще

Следующие приложения могут запускать службу переднего плана и вообще не отображаться в диспетчере задач:

• Приложения системного уровня
• Приложения безопасности; то есть приложения с ролью ROLE_EMERGENCY
• Устройства, находящиеся в демонстрационном режиме

Исключения из возможности остановки пользователями

Когда следующие типы приложений запускают службу переднего плана, они отображаются в диспетчере задач, но рядом с именем приложения нет кнопки «Стоп» , которую пользователь мог бы нажать:

• Приложения владельца устройства
• Приложения для владельцев профилей
• Постоянные приложения
• Приложения с ролью ROLE_DIALER

Используйте специально созданные API вместо служб переднего плана.

Во многих случаях использования существуют API-интерфейсы платформы или Jetpack, которые можно использовать для выполнения работы, для которой в противном случае вы могли бы использовать службу переднего плана. Если есть подходящий специальный API, вам почти всегда следует использовать его вместо службы переднего плана. Специально созданные API часто предоставляют дополнительные возможности, специфичные для конкретного случая использования, которые в противном случае вам пришлось бы создавать самостоятельно. Например, API Bubbles обрабатывает сложную логику пользовательского интерфейса для приложений обмена сообщениями, которым необходимо реализовать функции чата.

В документации по типам служб переднего плана перечислены хорошие альтернативы для использования вместо служб переднего плана.

Ограничения на запуск службы переднего плана из фона

Приложения, предназначенные для Android 12 или более поздней версии, не могут запускать службы переднего плана, пока приложение работает в фоновом режиме, за исключением нескольких особых случаев . Если приложение пытается запустить службу переднего плана, пока приложение работает в фоновом режиме, и служба переднего плана не удовлетворяет одному из исключительных случаев, система выдает исключение ForegroundServiceStartNotAllowedException .

Примечание. Если одно приложение вызывает Context.startForegroundService() для запуска службы переднего плана, принадлежащей другому приложению, эти ограничения применяются только в том случае, если оба приложения предназначены для Android 12 или более поздней версии.

Кроме того, если приложение хочет запустить приоритетную службу, которой требуются разрешения во время использования (например, разрешения для датчика тела, камеры, микрофона или местоположения), оно не может создать службу, пока приложение находится в фоновом режиме, даже если приложение попадает в одно из исключений из ограничений на фоновый запуск. Причина этого объясняется в разделе Ограничения на запуск служб переднего плана, которым требуются разрешения во время использования .

Исключения из ограничений фонового запуска

В следующих ситуациях ваше приложение может запускать службы переднего плана, даже если оно работает в фоновом режиме:

• Ваше приложение переходит из состояния, видимого пользователю, например из активности .
• Ваше приложение может запускать действие в фоновом режиме , за исключением случая, когда приложение имеет действие в стеке существующей задачи.

• Ваше приложение получает сообщение с высоким приоритетом с помощью Firebase Cloud Messaging .

  Примечание. Система может понизить приоритет сообщений с высоким приоритетом до обычного, если приложение не использует сообщения с высоким приоритетом для предоставления пользователю контента, чувствительного ко времени. Если приоритет сообщения понижен, ваше приложение не сможет запустить службу переднего плана, а попытка запустить ее приведет к возникновению исключения ForegroundServiceStartNotAllowedException .

  Поэтому рекомендуется проверить результат RemoteMessage.getPriority() и подтвердить, что это PRIORITY_HIGH() прежде чем пытаться запустить службу приоритетного плана. Рекомендации по сообщениям с высоким приоритетом и о том, когда их использовать, см. в FCM's documentation .

• Пользователь выполняет действие над элементом пользовательского интерфейса, связанным с вашим приложением. Например, они могут взаимодействовать с пузырьком , уведомлением , виджетом или действием.

• Ваше приложение вызывает точный сигнал тревоги для завершения действия, запрошенного пользователем.

• Ваше приложение – это текущий метод ввода устройства.

• Ваше приложение получает событие, связанное с переходом на геозону или распознавание активности .

• После того, как устройство перезагрузится и получит действие намерения ACTION_BOOT_COMPLETED , ACTION_LOCKED_BOOT_COMPLETED или ACTION_MY_PACKAGE_REPLACED в широковещательном приемнике .

  Примечание. Если ваше приложение предназначено для Android 14 или более поздней версии, существуют ограничения на запуск определенных типов служб переднего плана из приемника BOOT_COMPLETED . Дополнительные сведения см. в разделе Ограничения на широковещательные приемники BOOT_COMPLETED запускающие службы переднего плана .

• Ваше приложение получает действие намерения ACTION_TIMEZONE_CHANGED , ACTION_TIME_CHANGED или ACTION_LOCALE_CHANGED в широковещательном приемнике.

• Ваше приложение получает событие ACTION_TRANSACTION_DETECTED от NfcService .

• Приложения с определенными системными ролями или разрешениями, например владельцами устройств и владельцами профилей .

• Ваше приложение использует диспетчер устройств Companion и объявляет разрешение REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND или разрешение REQUEST_COMPANION_RUN_IN_BACKGROUND . По возможности используйте REQUEST_COMPANION_START_FOREGROUND_SERVICES_FROM_BACKGROUND .

• Пользователь отключает оптимизацию батареи для вашего приложения.

• Ваше приложение имеет разрешение SYSTEM_ALERT_WINDOW . Примечание. Если ваше приложение предназначено для Android 15 или более поздней версии, оно должно иметь разрешение SYSTEM_ALERT_WINDOW , и в настоящее время приложение должно иметь видимое окно наложения.

Ограничения на запуск служб переднего плана, которым требуются разрешения во время использования.

В Android 14 (уровень API 34) или более поздних версиях существуют особые ситуации, о которых следует знать, если вы запускаете службу переднего плана, которой требуются разрешения во время использования.

Если ваше приложение предназначено для Android 14 или более поздней версии, операционная система проверяет, когда вы создаете службу переднего плана, чтобы убедиться, что у вашего приложения есть все соответствующие разрешения для этого типа службы. Например, когда вы создаете службу переднего плана типа микрофон , операционная система проверяет, имеет ли ваше приложение в настоящее время разрешение RECORD_AUDIO . Если у вас нет такого разрешения, система выдает SecurityException .

Для разрешений во время использования это вызывает потенциальную проблему. Если у вашего приложения есть разрешение на использование, оно будет действовать только тогда, когда оно находится на переднем плане . Это означает, что если ваше приложение работает в фоновом режиме и пытается создать службу переднего плана типа камеры, местоположения или микрофона, система видит, что у вашего приложения в настоящее время нет необходимых разрешений, и выдает SecurityException .

Аналогично, если ваше приложение работает в фоновом режиме и создает службу работоспособности, которой требуется разрешение BODY_SENSORS_BACKGROUND , у приложения в настоящее время нет этого разрешения, и система выдает исключение. (Это неприменимо, если это служба работоспособности, которой требуются другие разрешения, например ACTIVITY_RECOGNITION .) Вызов PermissionChecker.checkSelfPermission() не предотвращает эту проблему. Если у вашего приложения есть разрешение на использование во время использования и оно вызывает checkSelfPermission() чтобы проверить, есть ли у него такое разрешение, метод возвращает PERMISSION_GRANTED , даже если приложение находится в фоновом режиме. Когда метод возвращает PERMISSION_GRANTED , он говорит: «Ваше приложение имеет это разрешение , пока оно используется ».

Примечание. В версиях Android ниже Android 14, если вы попытаетесь создать службу переднего плана, которой необходимы разрешения на использование, пока ваше приложение находится в фоновом режиме, система позволит вам создать службу, но служба не будет иметь доступ к необходимым ресурсам, и если он попытается их использовать, вы получите исключение. В Android 14 или более поздней версии ваше приложение получает исключение, как только пытается создать службу переднего плана.

По этой причине, если вашей службе переднего плана требуется разрешение на использование, вы должны вызвать Context.startForegroundService() или Context.bindService() пока ваше приложение имеет видимую активность, если только служба не попадает в одно из определенных исключений .

Исключения из ограничений на разрешения во время использования

В некоторых ситуациях, даже если служба переднего плана запускается, когда приложение работает в фоновом режиме , она все равно может получить доступ к информации о местоположении, камере и микрофоне, пока приложение работает на переднем плане («во время использования»).

В этих же ситуациях, если служба объявляет тип location службы переднего плана и запускается приложением, имеющим разрешение ACCESS_BACKGROUND_LOCATION , эта служба может постоянно получать доступ к информации о местоположении, даже когда приложение работает в фоновом режиме.

Следующий список содержит эти ситуации:

• Системный компонент запускает службу.
• Служба начинается с взаимодействия с виджетами приложения .
• Служба начинается с взаимодействия с уведомлением.
• Служба запускается как PendingIntent , отправляемый из другого видимого приложения.
• Служба запускается приложением, которое является контроллером политики устройства и работает в режиме владельца устройства.
• Служба запускается приложением, которое предоставляет VoiceInteractionService .
• Служба запускается приложением, имеющим привилегированное разрешение START_ACTIVITIES_FROM_BACKGROUND .

Определите, какие службы в вашем приложении затронуты.

При тестировании приложения запустите его службы переднего плана. Если запущенная служба ограничила доступ к местоположению, микрофону и камере, в Logcat появится следующее сообщение:

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