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

To help developers be more intentional with defining user-facing foreground services, Android 10 introduced the android:foregroundServiceType attribute within the <service> element.

If your app targets Android 14, it must specify appropriate foreground service types. As in previous versions of Android, multiple types can be combined. This list shows the foreground service types to choose from:

If a use case in your app isn't associated with any of these types, we strongly recommend that you migrate your logic to use WorkManager or user-initiated data transfer jobs.

The health, remoteMessaging, shortService, specialUse, and systemExempted types are new in Android 14.

The following code snippet provides an example of a foreground service type declaration in the manifest:

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

If an app that targets Android 14 doesn't define types for a given service in the manifest, then the system will raise MissingForegroundServiceTypeException upon calling startForeground() for that service.

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

如果以 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。

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

The system checks for proper use of foreground service types and confirms that the app has requested the proper runtime permissions or uses the required APIs. For instance, the system expects apps that use the foreground service type FOREGROUND_SERVICE_TYPE_LOCATION type to request either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION.

This implies that apps must follow a very specific order of operations when requesting permissions from the user and starting foreground services. Permissions must be requested and granted before the app attempts to call startForeground(). Apps that request the appropriate permissions after the foreground service has been started must change this order of operations and request the permission before starting the foreground service.

The specifics of platform enforcement appear in the sections labeled "runtime requirements" in the intended use cases and enforcement for each foreground service type section on this page.

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

In order to use a given foreground service type, you must declare a particular permission in your manifest file, you must fulfill specific runtime requirements, and your app must fulfill one of the intended sets of use cases for that type. The following sections explain the permission that you must declare, the runtime prerequisites, and the intended use cases for each type.

Камера

要在 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.

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

Foreground service type to declare in manifest under
android:foregroundServiceType
dataSync
Permission to declare in your manifest
FOREGROUND_SERVICE_DATA_SYNC
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_DATA_SYNC
Runtime prerequisites
None
Description

Data transfer operations, such as the following:

  • Data upload or download
  • Backup-and-restore operations
  • Import or export operations
  • Fetch data
  • Local file processing
  • Transfer data between a device and the cloud over a network
Alternatives

See Alternatives to data sync foreground services for detailed information.

Здоровье

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 runtime permission is 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, with a few exceptions. 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 геозон .

СМИ

Foreground service type to declare in manifest under
android:foregroundServiceType
mediaPlayback
Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PLAYBACK
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
Runtime prerequisites
None
Description
Continue audio or video playback from the background. Support Digital Video Recording (DVR) functionality on Android TV.
Alternatives
If you're showing picture-in-picture video, use Picture-in-Picture mode.

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

Тип службы переднего плана, который нужно объявить в манифесте в разделе
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 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

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

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

Foreground service type to declare in manifest under
android:foregroundServiceType
phoneCall
Permission to declare in your manifest
FOREGROUND_SERVICE_PHONE_CALL
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_PHONE_CALL
Runtime prerequisites

At least one of these conditions must be true:

  • App is the default dialer app through the ROLE_DIALER role.
Description

Continue an ongoing call using the ConnectionService APIs.

Alternatives

If you need to make phone, video, or VoIP calls, consider using the android.telecom library.

Consider using CallScreeningService to screen calls.

Удаленный обмен сообщениями

Foreground service type to declare in manifest under
android:foregroundServiceType
remoteMessaging
Permission to declare in your manifest
FOREGROUND_SERVICE_REMOTE_MESSAGING
Constant to pass to startForeground()
FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Runtime prerequisites
None
Description
Transfer text messages from one device to another. Assists with continuity of a user's messaging tasks when they switch devices.

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

Тип службы переднего плана, который нужно объявить в манифесте в разделе
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 前台服务类型之外，开发者还应在清单中声明用例。为此，他们会在 <service> 元素内指定 <property> 元素。这些值和相应的应用场景 。用途 您提供的案例均为自由形式，因此，您应确保提供足够的 相关信息，让审核人员了解您为何需要使用 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 для использования типов приоритетных служб

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