Los tipos de servicio en primer plano son obligatorios

Para permitir que los desarrolladores sean más conscientes con la definición de los servicios en primer plano para el usuario, en Android 10, se introdujo el atributo android:foregroundServiceType dentro del elemento <service>.

Si tu app está orientada a Android 14, debe especificar los tipos correctos de servicio en primer plano. Al igual que en versiones anteriores de Android, se pueden combinar varios tipos de servicios. En esta lista, se muestran los tipos de servicios en primer plano que puedes elegir:

Si un caso de uso en tu app no está asociado con ninguno de estos tipos, te recomendamos que migres la lógica para usar WorkManager o tareas de transferencia de datos que inicia el usuario..

Los tipos health, remoteMessaging, shortService, specialUse y systemExempted son nuevos en Android 14.

En el siguiente fragmento de código, se brinda el ejemplo de una declaración de tipo de servicio en primer plano en el manifiesto:

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

Si una app orientada a Android 14 no define tipos para un servicio determinado en el manifiesto, el sistema generará MissingForegroundServiceTypeException cuando se llame a startForeground() para ese servicio.

Declara un nuevo permiso para usar tipos de servicio en primer plano

如果以 Android 14 为目标平台的应用使用前台服务，则必须根据前台服务类型声明 Android 14 中引入的特定权限。这些权限显示在本页每种前台服务类型的预期用例和强制执行部分中标记为“您必须在清单文件中声明的权限”的部分。

所有这些权限都定义为一般权限，并默认授予。用户无法撤消这些权限。

Incluye el tipo de servicio en primer plano durante el tiempo de ejecución

The best practice for applications starting foreground services is to use the ServiceCompat version of startForeground() (available in androidx-core 1.12 and higher) where you pass in a bitwise integer of foreground service types. You can choose to pass one or more type values.

Usually, you should declare only the types required for a particular use case. This makes it easier to meet the system's expectations for each foreground service type. In cases where a foreground service is started with multiple types, then the foreground service must adhere to the platform enforcement requirements of all types.

ServiceCompat.startForeground(0, notification, FOREGROUND_SERVICE_TYPE_LOCATION)

If the foreground service type is not specified in the call, the type defaults to the values defined in the manifest. If you didn't specify the service type in the manifest, the system throws MissingForegroundServiceTypeException.

If the foreground service needs new permissions after you launch it, you should call startForeground() again and add the new service types. For example, suppose a fitness app runs a running-tracker service that always needs location information, but might or might not need media permissions. You would need to declare both location and mediaPlayback in the manifest. If a user starts a run and just wants their location tracked, your app should call startForeground() and pass just the location service type. Then, if the user wants to start playing audio, call startForeground() again and pass location|mediaPlayback.

Verificaciones del tiempo de ejecución del sistema

系统会检查前台服务类型的使用是否恰当，并确认应用是否已请求适当的运行时权限或使用所需的 API。例如，系统希望使用前台服务类型 FOREGROUND_SERVICE_TYPE_LOCATION 的应用请求 ACCESS_COARSE_LOCATION 或 ACCESS_FINE_LOCATION。

这意味着，在向用户请求权限和启动前台服务时，应用必须遵循非常具体的操作顺序。应用在尝试调用 startForeground() 之前，必须先请求并获得所需的权限。在启动前台服务后请求相应权限的应用必须更改此顺序，并在启动前台服务之前请求该权限。

本页面的每种前台服务类型的预期用例和强制执行部分中标记为“运行时要求”的部分列出了平台强制执行的具体内容。

Casos de uso previstos y aplicación forzosa para cada tipo de servicio en primer plano

Para usar un tipo determinado de servicio en primer plano, debes declarar un permiso particular en tu archivo de manifiesto, además de cumplir con requisitos específicos del tiempo de ejecución. Tu app también debe cumplir con uno de los conjuntos de casos de uso previstos para ese tipo. En las siguientes secciones, se explica el permiso que debes declarar, los requisitos previos del tiempo de ejecución y los casos de uso previstos para cada tipo.

Cámara

要在 android:foregroundServiceType 下在清单中声明的前台服务类型

camera

在清单中声明的权限

FOREGROUND_SERVICE_CAMERA

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_CAMERA

运行时前提条件

请求并获得 CAMERA 运行时权限

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

说明

继续在后台访问相机，例如支持多任务的视频聊天应用。

Dispositivo conectado

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:

Declare at least one of the following permissions in your manifest:
Request and be granted at least one of the following runtime permissions:
Call UsbManager.requestPermission()

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.

Sincronización de datos

Tipo de servicio en primer plano que se declarará en el manifiesto en

android:foregroundServiceType

dataSync

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_DATA_SYNC

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_DATA_SYNC

Requisitos previos del entorno de ejecución

Ninguno

Descripción

Operaciones de transferencia de datos, como las siguientes:

Sube o descarga de datos
Operaciones de copia de seguridad y restablecimiento
Operaciones de importación o exportación
Cómo obtener datos
Procesamiento de archivos locales
Cómo transferir datos entre un dispositivo y la nube a través de una red

Alternativas

Consulta Alternativas a los servicios en primer plano de sincronización de datos para obtener información detallada.

Salud

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

health

在清单中声明的权限

FOREGROUND_SERVICE_HEALTH

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_HEALTH

运行时前提条件

必须至少满足以下其中一个条件：

在清单中声明 HIGH_SAMPLING_RATE_SENSORS 权限。
至少请求并被授予以下其中一项运行时权限：
- 在 API 级别 35 及更低级别上使用 BODY_SENSORS
- READ_HEART_RATE
- READ_SKIN_TEMPERATURE
- READ_OXYGEN_SATURATION
- ACTIVITY_RECOGNITION

注意：BODY_SENSORS 和基于传感器的读取运行时权限受“在使用时”限制。因此，除非您已获得 BODY_SENSORS_BACKGROUND（API 级别 33 到 35）或 READ_HEALTH_DATA_IN_BACKGROUND（API 级别 36 及更高级别）权限，否则您无法创建在应用处于后台运行时使用身体传感器的 health 前台服务。如需了解详情，请参阅与启动需要使用时权限的前台服务相关的限制。

说明

为健身类别的应用（例如锻炼追踪器）提供支持的所有长时间运行的用例。

Ubicación

要在清单中的以下位置声明的前台服务类型

android:foregroundServiceType

location

在清单中声明的权限

FOREGROUND_SERVICE_LOCATION

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_LOCATION

运行时前提条件

用户必须已启用位置信息服务，并且应用必须至少获得以下一项运行时权限：

注意：如需检查用户是否已启用位置信息服务以及是否已授予对运行时权限的访问权限，请使用 PermissionChecker#checkSelfPermission()

注意：位置信息运行时权限受“使用期间”限制。因此，除非您已获得 ACCESS_BACKGROUND_LOCATION 运行时权限，否则无法在应用在后台运行时创建 location 前台服务。如需了解详情，请参阅与启动需要“使用时”权限的前台服务相关的限制。

说明

需要位置信息使用权的长时间运行的用例，例如导航和位置信息分享。

替代方案

如果您的应用需要在用户到达特定位置时触发，请考虑改用 Geofence API。

Contenido multimedia

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType: mediaPlayback
在清单中声明的权限: FOREGROUND_SERVICE_MEDIA_PLAYBACK
要传递给 startForeground() 的常量: FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK
运行时前提条件: 无
说明: 在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
替代方案: 如果您要显示画中画视频，请使用画中画模式。

Proyección de contenido multimedia

要在清单中的以下位置声明的前台服务类型
android:foregroundServiceType: mediaProjection
在清单中声明的权限: FOREGROUND_SERVICE_MEDIA_PROJECTION
要传递给 startForeground() 的常量: FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
运行时前提条件: 在启动前台服务之前调用 createScreenCaptureIntent() 方法。这样做会向用户显示权限通知；用户必须先授予权限，您才能创建服务。; 创建前台服务后，您可以调用 MediaProjectionManager.getMediaProjection()。
说明: 使用 MediaProjection API 将内容投影到非主要显示屏或外部设备。这些内容不必全都为媒体内容。
替代方案: 如需将媒体流式传输到其他设备，请使用 Google Cast SDK。

Micrófono

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.

Llamada telefónica

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 has declared the MANAGE_OWN_CALLS permission in its manifest file.

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.

Mensajería remota

Tipo de servicio en primer plano que se declarará en el manifiesto en
android:foregroundServiceType: remoteMessaging
Permiso para declarar en tu manifiesto: FOREGROUND_SERVICE_REMOTE_MESSAGING
Constante para pasar a startForeground(): FOREGROUND_SERVICE_TYPE_REMOTE_MESSAGING
Requisitos previos del entorno de ejecución: Ninguno
Descripción: Transfiere mensajes de texto de un dispositivo a otro. Brinda asistencia para la continuidad de las tareas de mensajería de un usuario cuando este cambia de dispositivo.

Servicio corto

Tipo de servicio en primer plano que se declarará en el manifiesto en

android:foregroundServiceType

shortService

Permiso para declarar en tu manifiesto

Ninguno

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_SHORT_SERVICE

Requisitos previos del entorno de ejecución

Ninguno

Descripción

Finaliza con rapidez tareas importantes que no se puedan interrumpir ni posponer.

Este tipo tiene algunas características únicas:

Solo se puede ejecutar por un período breve (alrededor de 3 minutos).
No admite servicios fijos en primer plano.
No se pueden iniciar otros servicios en primer plano.
No requiere un permiso específico para el tipo, aunque sí el permiso FOREGROUND_SERVICE.
Un shortService solo puede cambiar a otro tipo de servicio si la app es actualmente apta para iniciar un nuevo servicio en primer plano.
Un servicio en primer plano puede cambiar su tipo a shortService en cualquier momento, en cuyo punto comienza el período de tiempo de espera.

El tiempo de espera para shortService comienza desde el momento en que se llama a Service.startForeground(). Se espera que la app llame a Service.stopSelf() o Service.stopForeground() antes de que se agote el tiempo de espera. De lo contrario, se llama al nuevo Service.onTimeout(), lo que les brinda a las apps una breve oportunidad para llamar a stopSelf() o stopForeground() para detener su servicio.

Poco tiempo después de llamar a Service.onTimeout(), la app entra en un estado almacenado en caché y ya no se considera en primer plano, a menos que el usuario interactúe, de manera activa, con la app. Poco tiempo después de que la app se almacena en caché, y el servicio no se detiene, la app recibe un mensaje de ANR. Este mensaje menciona FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. Por estos motivos, te recomendamos que, como práctica recomendada, implementes la devolución de llamada a Service.onTimeout().

La devolución de llamada a Service.onTimeout() no existe en Android 13 y versiones anteriores. Si el mismo servicio se ejecuta en esos dispositivos, no recibirá un tiempo de espera ni un mensaje de ANR. Asegúrate de que el servicio se detenga en cuanto finalice la tarea de procesamiento, incluso si todavía no recibió la devolución de llamada a Service.onTimeout().

Es importante tener en cuenta que, si no se respeta el tiempo de espera de shortService, la app mostrará un error de ANR, incluso si tiene otros servicios en primer plano válidos u otros procesos del ciclo de vida de la app en ejecución.

Si una app es visible para el usuario o satisface una de las exenciones que permiten que se inicien los servicios en primer plano desde el segundo plano, volver a llamar a Service.StartForeground() con el parámetro FOREGROUND_SERVICE_TYPE_SHORT_SERVICE extiende el tiempo de espera por otros 3 minutos. Si la app no es visible para el usuario y no satisface una de las exenciones, cualquier intento de iniciar otro servicio en primer plano, independientemente del tipo, producirá ForegroundServiceStartNotAllowedException.

Si un usuario inhabilita la optimización de la batería de tu app, de todos modos, se verá afectada por el tiempo de espera del servicio en primer plano de shortService.

Si inicias un servicio en primer plano que incluye el tipo shortService y otro tipo de servicio en primer plano, el sistema ignora la declaración del tipo shortService. Sin embargo, el servicio debe cumplir con los requisitos previos de los otros tipos declarados. Para obtener más información, consulta la documentación de los servicios en primer plano.

Uso especial

要在清单中声明的前台服务类型

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>

Sistema exento

Foreground service type to declare in manifest under

android:foregroundServiceType

systemExempted

Permission to declare in your manifest

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Constant to pass to startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Runtime prerequisites

None

Description

Reserved for system applications and specific system integrations, to continue to use foreground services.

To use this type, an app must meet at least one of the following criteria:

Device is in demo mode state
App is a Device Owner
App is a Profiler Owner
Safety Apps that have the ROLE_EMERGENCY role
Device Admin apps
Apps holding SCHEDULE_EXACT_ALARM or USE_EXACT_ALARM permission and are using Foreground Service to continue alarms in the background, including haptics-only alarms.
VPN apps (configured using Settings > Network & Internet > VPN)

Otherwise, declaring this type causes the system to throw a ForegroundServiceTypeNotAllowedException.

Aplicación forzosa de las políticas de Google Play para usar tipos de servicios en primer plano

Si tu app se segmenta para Android 14 o versiones posteriores, deberás declarar los tipos de servicios en primer plano de la app en la página Contenido de la app de Play Console (Política > Contenido de la app). Para obtener más información sobre cómo declarar los tipos de servicios en primer plano en Play Console, consulta Información sobre los requisitos de los intents de pantalla completa y los servicios en primer plano.

Los tipos de servicio en primer plano son obligatorios Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Declara un nuevo permiso para usar tipos de servicio en primer plano

Incluye el tipo de servicio en primer plano durante el tiempo de ejecución

Verificaciones del tiempo de ejecución del sistema

Casos de uso previstos y aplicación forzosa para cada tipo de servicio en primer plano

Cámara

Dispositivo conectado

Sincronización de datos

Salud

Ubicación

Contenido multimedia

Proyección de contenido multimedia

Micrófono

Llamada telefónica

Mensajería remota

Servicio corto

Uso especial

Sistema exento

Aplicación forzosa de las políticas de Google Play para usar tipos de servicios en primer plano

Los tipos de servicio en primer plano son obligatorios