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

为了帮助开发者更有目的地定义面向用户的前台服务，Android 10 在 <service> 元素内引入了 android:foregroundServiceType 属性。

如果您的应用以 Android 14 为目标平台，则必须指定适当的前台服务类型。与以前的 Android 版本一样，可组合使用多个类型。下面列出了可供选择的前台服务类型：

如果应用中的用例与这些类型均不相关，强烈建议您迁移逻辑以使用 WorkManager 或用户发起的数据传输作业。

Android 14 中新增了 health, remoteMessaging, shortService, specialUse 和 systemExempted 类型。

以下代码段提供了一个清单中的前台服务类型声明示例：

<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 为目标平台的应用未在清单中定义给定服务的类型，系统会在调用 startForeground() 时引发 MissingForegroundServiceTypeException。

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

Если приложения, предназначенные для 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 , пока ваше приложение находится в фоновом режиме, за некоторыми исключениями . Дополнительные сведения см. в разделе Ограничения на запуск служб переднего плана, которым требуются разрешения во время использования .

Описание

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

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

Тип службы переднего плана, который нужно объявить в манифесте в разделе
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
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
health
Разрешение на объявление в вашем манифесте
FOREGROUND_SERVICE_HEALTH
Константа для передачи в startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
Предварительные условия выполнения

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

Примечание: разрешения BODY_SENSORS и READ на основе датчиков накладываются на ограничения во время использования. По этой причине вы не можете создать службу переднего плана health , которая использует датчики тела, пока ваше приложение находится в фоновом режиме, если вам не предоставлены разрешения BODY_SENSORS_BACKGROUND (уровень API 33–35) или READ_HEALTH_DATA_IN_BACKGROUND (уровень API 36 и выше). Для получения дополнительной информации см. Ограничения на запуск служб переднего плана, которым требуются разрешения во время использования .

Описание

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

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

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

Микрофон

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType
microphone
在清单中声明的权限
FOREGROUND_SERVICE_MICROPHONE
要传递给 startForeground() 的常量
FOREGROUND_SERVICE_TYPE_MICROPHONE
运行时前提条件

请求并获得 RECORD_AUDIO 运行时权限。

注意：RECORD_AUDIO 运行时权限受使用时限制的约束。因此，除少数例外情况外，您无法在应用在后台运行时创建 microphone 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

在后台继续捕获麦克风内容，例如录音器或通信应用。

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

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