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

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

Камера

Тип службы переднего плана, который необходимо указать в манифесте в разделе android:foregroundServiceType
camera
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_CAMERA
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
Предварительные условия выполнения

Запросите и получите разрешение на использование CAMERA в режиме реального времени.

Описание

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

Подключенное устройство

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
connectedDevice
Разрешение объявить в своем манифесте
FOREGROUND_SERVICE_CONNECTED_DEVICE
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Предварительные требования для выполнения

Хотя бы одно из следующих условий должно быть истинным:

Описание

Взаимодействие с внешними устройствами, для которых требуется подключение Bluetooth, NFC, ИК-порт, USB или сетевое соединение.

Альтернативы

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

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

Синхронизация данных

Тип службы переднего плана, который необходимо указать в манифесте.
android:foregroundServiceType
dataSync
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_DATA_SYNC
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Предварительные условия выполнения
Никто
Описание

Операции по передаче данных, такие как следующие:

  • Загрузка или скачивание данных
  • Операции резервного копирования и восстановления
  • Импортные или экспортные операции
  • Получить данные
  • Локальная обработка файлов
  • Передача данных между устройством и облаком по сети.
Альтернативы

Подробную информацию см. в разделе «Альтернативы службам синхронизации данных в фоновом режиме» .

Здоровье

Тип службы переднего плана для объявления в манифесте
android:foregroundServiceType
health
Разрешение на объявление в вашем манифесте
FOREGROUND_SERVICE_HEALTH
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Предварительные условия выполнения

Должно быть выполнено хотя бы одно из следующих условий:

Описание

Любые долгосрочные сценарии использования для поддержки приложений в категории фитнеса, например, трекеров тренировок.

Расположение

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
location
Разрешение объявить в своем манифесте
FOREGROUND_SERVICE_LOCATION
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
Предварительные требования для выполнения

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

Описание

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

Альтернативы

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

СМИ

Тип службы переднего плана, который необходимо указать в манифесте.
android:foregroundServiceType
mediaPlayback
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Предварительные условия выполнения
Никто
Описание

Продолжить воспроизведение аудио или видео в фоновом режиме. Поддерживается функция цифровой видеозаписи (DVR) на Android TV .

Альтернативы

Если вы воспроизводите видео в режиме «картинка в картинке», используйте этот режим .

Обработка медиафайлов

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
mediaProcessing
Разрешение объявить в своем манифесте
FOREGROUND_SERVICE_MEDIA_PROCESSING
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING
Предварительные требования для выполнения
Никто
Описание

Сервис для выполнения трудоемких операций с медиаресурсами, таких как преобразование мультимедиа в разные форматы. Система позволяет этой службе работать ограниченное время; при нормальных обстоятельствах этот лимит времени будет составлять 6 часов из каждых 24. (Этот лимит является общим для всех служб переднего плана mediaProcessing приложения.)

Ваше приложение должно вручную остановить службу обработки мультимедиа в следующем сценарии:

  • Когда операция перекодирования завершится или достигнет состояния сбоя, вызовите службу Service.stopForeground() и Service.stopSelf() чтобы полностью остановить службу.

Если период тайм-аута достигнут, система вызывает метод службы Service.onTimeout(int, int) . В это время у службы есть несколько секунд для вызова Service.stopSelf() . Если служба не вызывает Service.stopSelf() , произойдет ANR с этим сообщением об ошибке: «Служба переднего плана <fgs_type> не остановилась в течение времени ожидания: <comComponent_name> ».

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

Проекция СМИ

Тип службы переднего плана, который необходимо указать в манифесте.
android:foregroundServiceType
mediaProjection
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_MEDIA_PROJECTION
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
Предварительные условия выполнения

Перед запуском службы переднего плана вызовите метод createScreenCaptureIntent() . Это отобразит пользователю уведомление о необходимости разрешения; пользователь должен предоставить разрешение, прежде чем вы сможете создать службу.

После создания службы переднего плана вы можете вызвать MediaProjectionManager.getMediaProjection() .

Описание

Проецируйте контент на дополнительный дисплей или внешнее устройство, используя API MediaProjection . Этот контент не обязательно должен быть исключительно медиаконтентом.

Альтернативы

Для потоковой передачи мультимедиа на другое устройство используйте SDK Google Cast .

Микрофон

Тип службы переднего плана, который необходимо указать в манифесте.
android:foregroundServiceType
microphone
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_MICROPHONE
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Предварительные условия выполнения

Запросите и получите разрешение RECORD_AUDIO во время выполнения.

Описание

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

Телефонный звонок

Тип службы переднего плана, который необходимо указать в манифесте.
android:foregroundServiceType
phoneCall
Разрешение на декларирование в вашем манифесте
FOREGROUND_SERVICE_PHONE_CALL
Константа, передаваемая в startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Предварительные условия выполнения

По крайней мере одно из этих условий должно быть истинным:

  • В файле манифеста приложения указано разрешение MANAGE_OWN_CALLS .
  • Приложение является приложением для набора номера по умолчанию благодаря роли ROLE_DIALER .
Описание

Продолжите текущий вызов, используя API ConnectionService .

Альтернативы

Если вам нужно совершать телефонные, видеозвонки или звонки по VoIP, рассмотрите возможность использования библиотеки android.telecom .

Рекомендуется использовать CallScreeningService для фильтрации звонков.

Удалённая передача сообщений

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
remoteMessaging
Разрешение объявить в своем манифесте
FOREGROUND_SERVICE_REMOTE_MESSAGING
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Предварительные требования для выполнения
Никто
Описание
Передавайте текстовые сообщения с одного устройства на другое. Помогает обеспечить непрерывность выполнения задач пользователя по обмену сообщениями при переключении устройств.

Краткосрочное обслуживание

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
shortService
Разрешение объявить в вашем манифесте
Никто
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
Предварительные условия выполнения
Никто
Описание

Быстро завершайте важную работу, которую нельзя прервать или отложить.

Этот тип имеет ряд уникальных характеристик:

  • Может работать только в течение короткого периода времени (около 3 минут).
  • Нет поддержки закрепленных служб переднего плана.
  • Невозможно запустить другие службы переднего плана.
  • Не требует разрешения для конкретного типа , хотя все равно требуется разрешение FOREGROUND_SERVICE .
  • shortService может измениться на другой тип службы только в том случае, если приложение в настоящее время имеет право запускать новую службу переднего плана.
  • Служба переднего плана может изменить свой тип на shortService в любое время, после чего начинается период ожидания.

Таймаут для shortService начинается с момента вызова Service.startForeground() . Ожидается, что приложение вызовет Service.stopSelf() или Service.stopForeground() до истечения времени ожидания. В противном случае вызывается новый Service.onTimeout() , предоставляющий приложениям краткую возможность вызвать stopSelf() или stopForeground() , чтобы остановить службу.

Через некоторое время после вызова Service.onTimeout() приложение переходит в кэшированное состояние и больше не считается находящимся на переднем плане, если только пользователь не взаимодействует с приложением активно. Через некоторое время после того, как приложение кэшируется и служба не остановлена, приложение получает сообщение ANR . В сообщении ANR упоминается FOREGROUND_SERVICE_TYPE_SHORT_SERVICE . По этим причинам рекомендуется реализовать обратный вызов Service.onTimeout() .

Обратный вызов Service.onTimeout() не существует в Android 13 и более ранних версиях. Если та же служба работает на таких устройствах, она не получает тайм-аут и не получает ANR. Убедитесь, что ваша служба останавливается, как только завершает задачу обработки, даже если она еще не получила обратный вызов Service.onTimeout() .

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

Если приложение видно пользователю или удовлетворяет одному из исключений , позволяющих запускать службы переднего плана из фонового режима, повторный вызов Service.StartForeground() с параметром FOREGROUND_SERVICE_TYPE_SHORT_SERVICE продлевает время ожидания еще на 3 минуты. Если приложение не видно пользователю и не удовлетворяет ни одному из исключений , любая попытка запустить другую службу переднего плана, независимо от типа, вызывает ForegroundServiceStartNotAllowedException .

Если пользователь отключает оптимизацию заряда батареи для вашего приложения, на это все равно влияет тайм-аут shortService FGS.

Если вы запускаете службу переднего плана, включающую тип shortService и другой тип службы переднего плана, система игнорирует объявление типа shortService . Однако служба по-прежнему должна соответствовать требованиям других объявленных типов. Дополнительные сведения см. в документации по службам Foreground .

Специальное использование

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
specialUse
Разрешение объявить в вашем манифесте
FOREGROUND_SERVICE_SPECIAL_USE
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_SPECIAL_USE
Предварительные условия выполнения
Никто
Описание

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

Помимо объявления типа службы переднего плана FOREGROUND_SERVICE_TYPE_SPECIAL_USE , разработчики должны объявить варианты использования в манифесте. Для этого они указывают элемент <property> внутри элемента <service> . Эти значения и соответствующие варианты использования проверяются, когда вы отправляете свое приложение в консоль Google Play. Предоставленные вами варианты использования представлены в свободной форме, и вы должны обязательно предоставить достаточно информации, чтобы рецензент мог понять, почему вам нужно использовать тип 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>

Система освобождена от ограничений

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
systemExempted
Разрешение объявить в своем манифесте
FOREGROUND_SERVICE_SYSTEM_EXEMPTED
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED
Предварительные требования для выполнения
Никто
Описание

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

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

Применение правил Google Play к использованию типов служб переднего плана

If your app targets Android 14 or higher, you'll need to declare your app's foreground service types in the Play Console's app content page (Policy > App content). For more information on how to declare your foreground service types in Play Console, see Understanding foreground service and full-screen intent requirements.