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:
camera
connectedDevice
dataSync
health
location
mediaPlayback
mediaProjection
microphone
phoneCall
remoteMessaging
shortService
specialUse
systemExempted
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
If apps that target Android 14 use a foreground service, they must declare a specific permission, based on the foreground service type, that Android 14 introduces. These permissions appear in the sections labeled "permission that you must declare in your manifest file" in the intended use cases and enforcement for each foreground service type section on this page.
All of the permissions are defined as normal permissions and are granted by default. Users cannot revoke these permissions.
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
El sistema controla el uso adecuado de los tipos de servicios en primer plano y confirma si la app solicitó los permisos de tiempo de ejecución correspondientes o si usa las APIs requeridas.
Por ejemplo, el sistema espera que las apps que usan el tipo FOREGROUND_SERVICE_TYPE_LOCATION
de servicio en primer plano soliciten ACCESS_COARSE_LOCATION
o ACCESS_FINE_LOCATION
.
Esto implica que las apps deben seguir un orden de operaciones muy específico cuando le solicitan permisos al usuario e inician servicios en primer plano. Se deben solicitar y obtener los permisos correspondientes antes de que la app llame a startForeground()
. Las apps que solicitan los permisos correctos después de que se inicia el servicio en primer plano deben cambiar este orden de operaciones y solicitar el permiso antes de iniciar el servicio en primer plano.
Los detalles de la aplicación forzosa de la plataforma aparecen en las secciones etiquetadas como "requisitos del tiempo de ejecución" en las secciones de casos de uso previstos y de aplicación forzosa de cada tipo de servicio en primer plano en esta página.
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
- Foreground service type to declare in manifest under
android:foregroundServiceType
camera
- Permission to declare in your manifest
FOREGROUND_SERVICE_CAMERA
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_CAMERA
- Runtime prerequisites
Request and be granted the
CAMERA
runtime permissionNote: The
CAMERA
runtime permission is subject to while-in-use restrictions. For this reason, you cannot create acamera
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 to access the camera from the background, such as video chat apps that allow for multitasking.
Dispositivo conectado
- Tipo de servicio en primer plano que se declarará en el manifiesto en
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:
Solicita y obtén al menos uno de los siguientes permisos de tiempo de ejecución:
Llamada a
UsbManager.requestPermission()
- Descripción
Interacciones con dispositivos externos que requieren una conexión Bluetooth, NFC, IR, USB o de red.
- Alternativas
Si la app necesita realizar una transferencia de datos continua a un dispositivo externo, considera usar el administrador de dispositivos complementarios. Usa la API de presencia de dispositivos complementarios para ayudar a que tu app siga ejecutándose mientras el dispositivo complementario esté dentro del alcance.
Si la app necesita buscar dispositivos Bluetooth, considera usar la API de búsqueda de Bluetooth.
Sincronización de datos
- 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.
Salud
- Tipo de servicio en primer plano que se declarará en el manifiesto en
android:foregroundServiceType
health
- Permiso para declarar en tu manifiesto
FOREGROUND_SERVICE_HEALTH
- Constante para pasar a
startForeground()
FOREGROUND_SERVICE_TYPE_HEALTH
- Requisitos previos del entorno de ejecución
Debe cumplirse mínimo una de las siguientes condiciones:
Declara el permiso
HIGH_SAMPLING_RATE_SENSORS
en tu manifiesto.Solicita y obtén al menos uno de los siguientes permisos de tiempo de ejecución:
Nota: El permiso de tiempo de ejecución
BODY_SENSORS
está sujeto a restricciones durante el uso. Por este motivo, no puedes crear un servicio en primer planohealth
que use sensores corporales mientras tu app está en segundo plano, 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
Cualquier caso de uso de larga duración para admitir apps de la categoría de entrenamiento, como monitoreos de ejercicios
Ubicación
- Tipo de servicio en primer plano que se declarará en el manifiesto en
android:foregroundServiceType
location
- Permiso para declarar en tu manifiesto
FOREGROUND_SERVICE_LOCATION
- Constante para pasar a
startForeground()
FOREGROUND_SERVICE_TYPE_LOCATION
- Requisitos previos del entorno de ejecución
El usuario debe haber habilitado los servicios de ubicación, y la app debe tener al menos uno de los siguientes permisos de tiempo de ejecución:
Nota: Para verificar que el usuario habilitó los servicios de ubicación y otorgó acceso a los permisos de tiempo de ejecución, usa
PermissionChecker#checkSelfPermission()
.Nota: Los permisos de tiempo de ejecución de la ubicación están sujetos a restricciones durante el uso. Por este motivo, no puedes crear un servicio en primer plano
location
mientras la app está en segundo plano, a menos que se te haya otorgado el permiso de tiempo de ejecuciónACCESS_BACKGROUND_LOCATION
. Para obtener más información, consulta Restricciones para iniciar servicios en primer plano que necesitan permisos durante el uso.- Descripción
Casos de uso de larga duración que requieren acceso a la ubicación, como la navegación y el uso compartido de la ubicación
- Alternativas
Si tu app debe activarse cuando el usuario llega a ubicaciones específicas, considera usar la API de geovallado.
Contenido multimedia
- 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.
Proyección de contenido multimedia
- Foreground service type to declare in manifest under
android:foregroundServiceType
mediaProjection
- Permission to declare in your manifest
FOREGROUND_SERVICE_MEDIA_PROJECTION
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION
- Runtime prerequisites
Call the
createScreenCaptureIntent()
method before starting the foreground service. Doing so shows a permission notification to the user; the user must grant the permission before you can create the service.After you have created the foreground service, you can call
MediaProjectionManager.getMediaProjection()
.- Description
Project content to non-primary display or external device using the
MediaProjection
APIs. This content doesn't have to be exclusively media content.- Alternatives
To stream media to another device, use the Google Cast SDK.
Micrófono
- Tipo de servicio en primer plano que se declarará en el manifiesto en
android:foregroundServiceType
microphone
- Permiso para declarar en tu manifiesto
FOREGROUND_SERVICE_MICROPHONE
- Constante para pasar a
startForeground()
FOREGROUND_SERVICE_TYPE_MICROPHONE
- Requisitos previos del entorno de ejecución
Solicita y obtén el permiso de tiempo de ejecución
RECORD_AUDIO
.Nota: El permiso de tiempo de ejecución
RECORD_AUDIO
está sujeto a restricciones durante el uso. Por este motivo, no puedes crear un servicio en primer planomicrophone
mientras tu app está en segundo plano, 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 con la captura de micrófono en segundo plano, como las grabadoras de voz o las apps de comunicación.
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 has declared the
- App is the default dialer app through the
ROLE_DIALER
role.
- App is the default dialer app through the
- 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
- Foreground service type to declare in manifest under
android:foregroundServiceType
shortService
- Permission to declare in your manifest
- None
- Constant to pass to
startForeground()
FOREGROUND_SERVICE_TYPE_SHORT_SERVICE
- Runtime prerequisites
- None
- Description
Quickly finish critical work that cannot be interrupted or postponed.
This type has some unique characteristics:
- Can only run for a short period of time (about 3 minutes).
- No support for sticky foreground services.
- Cannot start other foreground services.
- Doesn't require a type-specific permission, though it still
requires the
FOREGROUND_SERVICE
permission. - A
shortService
can only change to another service type if the app is currently eligible to start a new foreground service. - A foreground service can change its type to
shortService
at any time, at which point the timeout period begins.
The timeout for shortService begins from the moment that
Service.startForeground()
is called. The app is expected to callService.stopSelf()
orService.stopForeground()
before the timeout occurs. Otherwise, the newService.onTimeout()
is called, giving apps a brief opportunity to callstopSelf()
orstopForeground()
to stop their service.A short time after
Service.onTimeout()
is called, the app enters a cached state and is no longer considered to be in the foreground, unless the user is actively interacting with the app. A short time after the app is cached and the service has not stopped, the app receives an ANR. The ANR message mentionsFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
. For these reasons, it's considered best practice to implement theService.onTimeout()
callback.The
Service.onTimeout()
callback doesn't exist on Android 13 and lower. If the same service runs on such devices, it doesn't receive a timeout, nor does it ANR. Make sure that your service stops as soon as it finishes the processing task, even if it hasn't received theService.onTimeout()
callback yet.It's important to note that if the timeout of the
shortService
is not respected, the app will ANR even if it has other valid foreground services or other app lifecycle processes running.If an app is visible to the user or satisfies one of the exemptions that allow foreground services to be started from the background, calling
Service.StartForeground()
again with theFOREGROUND_SERVICE_TYPE_SHORT_SERVICE
parameter extends the timeout by another 3 minutes. If the app isn't visible to the user and doesn't satisfy one of the exemptions, any attempt to start another foreground service, regardless of type, causes aForegroundServiceStartNotAllowedException
.If a user disables battery optimization for your app, it's still affected by the timeout of shortService FGS.
If you start a foreground service that includes the
shortService
type and another foreground service type, the system ignores theshortService
type declaration. However, the service must still adhere to the prerequisites of the other declared types. For more information, see the Foreground services documentation.
Uso especial
- Tipo de servicio en primer plano que se declarará en el manifiesto en
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 usarspecialUse
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 en
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 y integraciones de sistemas específicos, para continuar 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
oUSE_EXACT_ALARM
y usan el servicio en primer plano para continuar con las alarmas en segundo plano, incluidas las alarmas solo táctiles Apps de VPN (configuradas con 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.