Укажите типы приоритетных служб.

Чтобы помочь разработчикам более тщательно определять службы переднего плана , ориентированные на пользователя, в Android 10 появился атрибут android:foregroundServiceType в элементе <service> .

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

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

Типы health, remoteMessaging, shortService, specialUse и systemExempted являются новыми в Android 14.

В следующем фрагменте кода представлен пример объявления типа службы переднего плана в манифесте:

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

Если приложение, предназначенное для Android 14, не определяет типы для данной службы в манифесте, система выдаст MissingForegroundServiceTypeException при вызове startForeground() для этой службы.

Объявить новое разрешение на использование типов служб переднего плана

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

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

Включить тип службы переднего плана во время выполнения

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

Обычно вам следует объявлять только те типы, которые необходимы для конкретного варианта использования. Это упрощает удовлетворение ожиданий системы для каждого типа приоритетных служб . В случаях, когда служба переднего плана запускается с несколькими типами, она должна соответствовать требованиям платформы всех типов.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

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

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

Проверка времени работы системы

Система проверяет правильность использования типов служб переднего плана и подтверждает, что приложение запросило правильные разрешения во время выполнения или использует необходимые API. Например, система ожидает, что приложения, использующие тип службы переднего плана FOREGROUND_SERVICE_TYPE_LOCATION , будут запрашивать либо ACCESS_COARSE_LOCATION , либо ACCESS_FINE_LOCATION .

Это означает, что приложения должны следовать очень определенному порядку операций при запросе разрешений у пользователя и запуске служб переднего плана. Разрешения должны быть запрошены и предоставлены до того, как приложение попытается вызвать startForeground() . Приложения, которые запрашивают соответствующие разрешения после запуска службы переднего плана, должны изменить этот порядок операций и запрашивать разрешение перед запуском службы переднего плана.

Особенности принудительного применения платформы представлены в разделах с надписью «Требования к среде выполнения» в предполагаемых вариантах использования и принудительном исполнении для каждого раздела типа службы приоритетного плана на этой странице.

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

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

Камера

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

Запросите и получите разрешение на выполнение CAMERA

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

Описание

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

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

Foreground service type to declare in manifest under
android:foregroundServiceType
connectedDevice
Permission to declare in your manifest
FOREGROUND_SERVICE_CONNECTED_DEVICE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
Runtime prerequisites

At least one of the following conditions must be true:

Description

Interactions with external devices that require a Bluetooth, NFC, IR, USB, or network connection.

Alternatives

If your app needs to do continuous data transfer to an external device, consider using the companion device manager instead. Use the companion device presence API to help your app stay running while the companion device is in range.

If your app needs to scan for bluetooth devices, consider using the Bluetooth scan API instead.

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

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

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

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

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

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

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

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

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

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

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

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

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

Здоровье

Foreground service type to declare in manifest under
android:foregroundServiceType
health
Permission to declare in your manifest
FOREGROUND_SERVICE_HEALTH
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Runtime prerequisites

At least one of the following conditions must be true:

Note: The BODY_SENSORS and sensor-based READ runtime permissions are subject to while-in-use restrictions. For this reason, you cannot create a health foreground service that uses body sensors while your app is in the background unless you've been granted the BODY_SENSORS_BACKGROUND (API level 33 to 35) or READ_HEALTH_DATA_IN_BACKGROUND (API level 36 and higher) permissions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Any long-running use cases to support apps in the fitness category such as exercise trackers.

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

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

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

Примечание. Чтобы проверить, включил ли пользователь службы определения местоположения, а также предоставил ли ему доступ к разрешениям среды выполнения, используйте PermissionChecker#checkSelfPermission()

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

Описание

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

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

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

СМИ

Тип службы переднего плана, который нужно объявить в манифесте в разделе
android:foregroundServiceType
mediaPlayback
Разрешение объявить в вашем манифесте
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Предварительные требования для выполнения
Никто
Описание
Продолжить воспроизведение аудио или видео в фоновом режиме. Поддержка функции цифровой видеозаписи (DVR) на Android TV .
Альтернативы
Если вы показываете видео «картинка в картинке», используйте режим «картинка в картинке» .

Медиа-проекция

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

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

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

Описание

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

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

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

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

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

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

Описание

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

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

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

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

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

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

Описание

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

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

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

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

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

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

Описание

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

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

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

Микрофон

Foreground service type to declare in manifest under
android:foregroundServiceType
microphone
Permission to declare in your manifest
FOREGROUND_SERVICE_MICROPHONE
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
Runtime prerequisites

Request and be granted the RECORD_AUDIO runtime permission.

Note: The RECORD_AUDIO runtime permission is subject to while-in-use restrictions. For this reason, you cannot create a microphone foreground service while your app is in the background, with a few exceptions. For more information, see Restrictions on starting foreground services that need while-in-use permissions.

Description

Continue microphone capture from the background, such as voice recorders or communication apps.

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

Тип службы переднего плана, который нужно объявить в манифесте в разделе
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
Предварительные условия выполнения
Никто
Описание

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

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

  • Устройство находится в состоянии демонстрационного режима
  • Приложение является владельцем устройства
  • Приложение является владельцем профайлера
  • Приложения безопасности с ролью ROLE_EMERGENCY
  • Приложения для администратора устройства
  • Приложения, имеющие разрешение SCHEDULE_EXACT_ALARM или USE_EXACT_ALARM , используют службу Foreground Service для продолжения подачи сигналов тревоги в фоновом режиме, включая сигналы тревоги только для тактильных сигналов.

  • Приложения VPN (настраиваются с помощью «Настройки» > «Сеть и Интернет» > «VPN» ).

    В противном случае объявление этого типа приведет к тому, что система выдаст исключение ForegroundServiceTypeNotAllowedException .

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

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