Tipos de servicios en primer plano

A partir de Android 14 (nivel de API 34), debes declarar un tipo de servicio apropiado para cada servicio en primer plano. Eso significa que debes declarar el tipo de servicio en el manifiesto de tu app y, además, solicitar el permiso de servicio en primer plano adecuado para ese tipo (además de solicitar el permiso FOREGROUND_SERVICE). Además, según el tipo de servicio en primer plano, es posible que debas solicitar permisos de tiempo de ejecución antes de iniciar el servicio.

Nota: En muchos casos, hay APIs diseñadas a tal fin que puedes usar en lugar de crear un tipo particular de servicio en primer plano. Cuando las APIs específicas están disponibles, suelen ser una mejor opción que crear un servicio en primer plano. Estas APIs se enumeran en las secciones Alternativas dentro de los tipos de servicios en primer plano adecuados.

Cámara

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

camera

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_CAMERA

Es la constante que se pasa a startForeground().

FOREGROUND_SERVICE_TYPE_CAMERA

Requisitos previos del entorno de ejecución

Solicita y obtén el permiso de tiempo de ejecución CAMERA

Nota: El permiso de tiempo de ejecución CAMERA está sujeto a restricciones durante el uso. Por este motivo, no puedes crear un servicio en primer plano de camera mientras la app está en segundo plano ni iniciar un servicio en primer plano de camera desde un receptor de BOOT_COMPLETED, con algunas excepciones. Para obtener más información, consulta Restricciones para iniciar servicios en primer plano que necesitan permisos durante el uso.

Descripción

Continúa accediendo a la cámara en segundo plano, como las apps de videochat que permiten realizar varias tareas a la vez.

Dispositivo conectado

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

android:foregroundServiceType

connectedDevice

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_CONNECTED_DEVICE

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE

Requisitos previos del entorno de ejecución

Debe cumplirse mínimo una de las siguientes condiciones:

• Declara mínimo uno de los siguientes permisos en tu manifiesto:

  • CHANGE_NETWORK_STATE
  • CHANGE_WIFI_STATE
  • CHANGE_WIFI_MULTICAST_STATE
  • NFC
  • TRANSMIT_IR

• Solicita y obtén al menos uno de los siguientes permisos de tiempo de ejecución:

  • BLUETOOTH_CONNECT
  • BLUETOOTH_ADVERTISE
  • BLUETOOTH_SCAN
  • UWB_RANGING

• Llamada a UsbManager.requestPermission()

Descripción

Interacciones con dispositivos externos que requieren una conexión Bluetooth, NFC, IR, USB o de red.

Nota: Si tu app realiza una operación de proyección o mensajería remota, usa el tipo de proyección de contenido multimedia o mensajería remota correspondiente en su lugar.

Alternativas

Si tu app necesita realizar una transferencia de datos continua a un dispositivo externo, considera usar el administrador de dispositivo complementario. Usa la API de ubicación de dispositivos complementarios para que la app se mantenga en ejecución mientras el dispositivo complementario esté dentro del alcance.

Si tu app necesita buscar dispositivos Bluetooth, considera usar la API de Bluetooth Scan.

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

Es la constante que se pasa 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

Nota: Las apps que se orientan a Android 15 o versiones posteriores no pueden iniciar un servicio en primer plano de sincronización de datos desde un receptor de emisión BOOT_COMPLETED. Para obtener más información, consulta Restricciones en los receptores de emisión BOOT_COMPLETED que inician servicios en primer plano.

Alternativas

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

Salud

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:

• Declare the HIGH_SAMPLING_RATE_SENSORS permission in your manifest.

• Request and be granted at least one of the following runtime permissions:

  • BODY_SENSORS on API 35 and lower
  • READ_HEART_RATE
  • READ_SKIN_TEMPERATURE
  • READ_OXYGEN_SATURATION
  • ACTIVITY_RECOGNITION

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 (between API level 33 and API level 35) or READ_HEALTH_DATA_IN_BACKGROUND (API level 36) 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.

Ubicación

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

android:foregroundServiceType

location

在清单中声明的权限

FOREGROUND_SERVICE_LOCATION

要传递给 startForeground() 的常量

FOREGROUND_SERVICE_TYPE_LOCATION

运行时前提条件

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

• ACCESS_COARSE_LOCATION
• ACCESS_FINE_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) 功能。

注意： 以 Android 15 或更高版本为目标平台的应用不得通过 BOOT_COMPLETED 广播接收器启动媒体播放前台服务。如需了解详情，请参阅对启动前台服务的 BOOT_COMPLETED 广播接收器的限制。

替代方案

如果您要显示画中画视频，请使用画中画模式。

Procesando archivos multimedia

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

android:foregroundServiceType

mediaProcessing

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_MEDIA_PROCESSING

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_MEDIA_PROCESSING

Requisitos previos del entorno de ejecución

Ninguno

Descripción

Servicio para realizar operaciones que requieren mucho tiempo en elementos multimedia, como la conversión de contenido multimedia a diferentes formatos. El sistema permite que este servicio se ejecute por un tiempo limitado; en circunstancias normales, este límite de tiempo sería de 6 horas cada 24. (Este límite se comparte con todos los servicios en primer plano de mediaProcessing de una app).

Tu app debe detener manualmente el servicio de procesamiento de contenido multimedia en la siguiente situación:

• Cuando la operación de transcodificación finalice o alcance un estado de falla, haz que el servicio llame a Service.stopForeground() y Service.stopSelf() para detenerlo por completo.

Si se alcanza el tiempo de espera, el sistema llama al método Service.onTimeout(int, int) del servicio. En este momento, el servicio tiene unos segundos para llamar a Service.stopSelf(). Si el servicio no llama a Service.stopSelf(), se producirá un error de ANR con este mensaje de error: "Un servicio en primer plano de <fgs_type> no se detuvo durante el tiempo de espera: <component_name>".

Nota: Service.onTimeout(int, int) no está disponible en Android 14 o versiones anteriores. En los dispositivos que ejecutan esas versiones, si un servicio de procesamiento de contenido multimedia alcanza el tiempo de espera, el sistema almacena la app de inmediato en caché. Por este motivo, tu app no debe esperar a recibir una notificación de tiempo de espera. En su lugar, debe finalizar el servicio en primer plano o cambiarlo a uno en segundo plano tan pronto como sea necesario.

Proyección de contenido multimedia

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

android:foregroundServiceType

mediaProjection

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_MEDIA_PROJECTION

Es la constante que se pasa a startForeground().

FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION

Requisitos previos del entorno de ejecución

Llama al método createScreenCaptureIntent() antes de iniciar el servicio en primer plano. De esta manera, se muestra una notificación de permiso al usuario, quien debe otorgar el permiso para que puedas crear el servicio.

Después de crear el servicio en primer plano, puedes llamar a MediaProjectionManager.getMediaProjection().

Descripción

Proyecta el contenido en un dispositivo externo o una pantalla no principal con las APIs de MediaProjection. No es necesario que este contenido sea solo multimedia.

Nota: Las apps que se orientan a Android 15 o versiones posteriores no pueden iniciar un servicio en primer plano de proyección multimedia desde un receptor de emisión BOOT_COMPLETED. Para obtener más información, consulta Restricciones en los receptores de emisión BOOT_COMPLETED que inician servicios en primer plano.

Alternativas

Para transmitir contenido multimedia a otro dispositivo, usa el SDK de Google Cast.

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 and you cannot launch a microphone foreground service from a BOOT_COMPLETED receiver, 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

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

android:foregroundServiceType

phoneCall

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_PHONE_CALL

Es la constante que se pasa a startForeground().

FOREGROUND_SERVICE_TYPE_PHONE_CALL

Requisitos previos del entorno de ejecución

Debe cumplirse al menos una de las siguientes condiciones:

• La app declaró el permiso MANAGE_OWN_CALLS en su archivo de manifiesto.

• La app es la app de teléfono predeterminada a través del rol ROLE_DIALER.

Nota: Las apps que se orientan a Android 15 o versiones posteriores no pueden iniciar un servicio en primer plano de llamada telefónica desde un receptor de emisión BOOT_COMPLETED. Para obtener más información, consulta Restricciones en los receptores de emisión BOOT_COMPLETED que inician servicios en primer plano.

Descripción

Continúa una llamada en curso con las APIs de ConnectionService.

Alternativas

Si necesitas hacer llamadas telefónicas, por video o por VoIP, considera usar la biblioteca android.telecom.

Considera usar CallScreeningService para filtrar llamadas.

Mensajería remota

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

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

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

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() 回调被视为一种最佳实践。

Android 13 及更低版本中不存在 Service.onTimeout() 回调。如果同一服务在此类设备上运行，则不会出现超时，也不会发生 ANR。确保您的服务在完成处理任务后立即停止，即使它尚未收到 Service.onTimeout() 回调也是如此。

请务必注意，如果未遵循 shortService 的超时设置，即使应用还有其他有效的前台服务或其他应用生命周期进程，应用也会遇到 ANR。

如果应用对用户可见，或满足允许从后台启动前台服务的某一豁免条件，则使用 FOREGROUND_SERVICE_TYPE_SHORT_SERVICE 参数再次调用 Service.StartForeground() 会将超时时间再延长 3 分钟。如果应用对用户不可见且不满足其中一个豁免条件，则尝试启动其他前台服务（无论其类型如何）都会导致 ForegroundServiceStartNotAllowedException。

即使用户为您的应用停用电池优化功能，仍然会受到 shortService FGS 的影响。

如果您启动包含 shortService 类型和另一个前台服务类型的前台服务，系统会忽略 shortService 类型声明。不过，该服务仍必须遵守其他声明类型的前提条件。如需了解详情，请参阅前台服务文档。

Uso especial

Tipo de servicio en primer plano para declarar en el manifiesto

android:foregroundServiceType

specialUse

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_SPECIAL_USE

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_SPECIAL_USE

Requisitos previos del entorno de ejecución

Ninguno

Descripción

Abarca todos los casos de uso válidos de servicios en primer plano que no están cubiertos por los otros tipos de servicios en primer plano.

Además de declarar el tipo de servicio en primer plano de FOREGROUND_SERVICE_TYPE_SPECIAL_USE, los desarrolladores deben declarar casos de uso en el manifiesto. Para ello, especifican el elemento <property> dentro del objeto <service>. Estos valores y los casos de uso correspondientes se revisan cuando envías tu app en Google Play Console. El uso son de formato libre, y debes asegurarte de proporcionar suficientes información para que el revisor pueda ver por qué necesitas usar specialUse el tipo de letra.

<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

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

android:foregroundServiceType

systemExempted

Permiso para declarar en tu manifiesto

FOREGROUND_SERVICE_SYSTEM_EXEMPTED

Constante para pasar a startForeground()

FOREGROUND_SERVICE_TYPE_SYSTEM_EXEMPTED

Requisitos previos del entorno de ejecución

Ninguno

Descripción

Reservado para aplicaciones del sistema, además de integraciones de sistemas específicos, para seguir usando los servicios en primer plano.

Para usar este tipo, una app debe cumplir con mínimo uno de los siguientes criterios:

• El dispositivo debe estar en modo de demostración
• La app debe ser del propietario del dispositivo
• La app debe ser del propietario del generador de perfiles.
• Apps de seguridad que tienen la función ROLE_EMERGENCY
• Apps de administración del dispositivo
• Apps que tienen el permiso SCHEDULE_EXACT_ALARM o USE_EXACT_ALARM

• Apps de VPN (configuradas mediante Configuración > Internet y redes > VPN)

  De lo contrario, declarar este tipo causa que el sistema arroje una ForegroundServiceTypeNotAllowedException.

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

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.