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:
cameraconnectedDevicedataSynchealthlocationmediaPlaybackmediaProjectionmicrophonephoneCallremoteMessagingshortServicespecialUsesystemExempted
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.
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
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.
Casos de uso previstos y aplicación forzosa para cada tipo de servicio en primer plano
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.
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
CAMERAruntime permissionNote: The
CAMERAruntime permission is subject to while-in-use restrictions. For this reason, you cannot create acameraforeground 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
- Foreground service type to declare in manifest under
android:foregroundServiceTypeconnectedDevice- 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:
- 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
- Foreground service type to declare in manifest under
android:foregroundServiceTypedataSync- 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:foregroundServiceTypehealth- Permiso para declarar en tu manifiesto
FOREGROUND_SERVICE_HEALTH- Es la constante que se pasa 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_SENSORSen tu manifiesto.Solicita y obtén al menos uno de los siguientes permisos de tiempo de ejecución:
BODY_SENSORSen el nivel de API 35 y versiones anterioresREAD_HEART_RATEREAD_SKIN_TEMPERATUREREAD_OXYGEN_SATURATIONACTIVITY_RECOGNITION
Nota: Los permisos de tiempo de ejecución de lectura
BODY_SENSORSy basados en sensores están sujetos a restricciones durante el uso. Por este motivo, no puedes crear un servicio en primer planohealthque use sensores corporales mientras tu app está en segundo plano, a menos que se te hayan otorgado los permisosBODY_SENSORS_BACKGROUND(nivel de API 33 a 35) oREAD_HEALTH_DATA_IN_BACKGROUND(nivel de API 36 y versiones posteriores). Para obtener más información, consulta Restringe el inicio de servicios en primer plano que necesiten 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
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypelocation- 在清单中声明的权限
FOREGROUND_SERVICE_LOCATION- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_LOCATION- 运行时前提条件
用户必须已启用位置信息服务,并且应用必须至少获得以下一项运行时权限:
注意:如需检查用户是否已启用位置信息服务以及是否已授予对运行时权限的访问权限,请使用
PermissionChecker#checkSelfPermission()注意:位置信息运行时权限受“使用期间”限制。因此,除非您已获得
ACCESS_BACKGROUND_LOCATION运行时权限,否则无法在应用在后台运行时创建location前台服务。如需了解详情,请参阅与启动需要“使用时”权限的前台服务相关的限制。- 说明
需要位置信息使用权的长时间运行的用例,例如导航和位置信息分享。
- 替代方案
如果您的应用需要在用户到达特定位置时触发,请考虑改用 Geofence API。
Contenido multimedia
- 要在清单中的以下位置声明的前台服务类型
android:foregroundServiceTypemediaPlayback- 在清单中声明的权限
FOREGROUND_SERVICE_MEDIA_PLAYBACK- 要传递给
startForeground()的常量 FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK- 运行时前提条件
- 无
- 说明
- 在后台继续播放音频或视频。在 Android TV 上支持数字视频录制 (DVR) 功能。
- 替代方案
- 如果您要显示画中画视频,请使用画中画模式。
Proyección de contenido multimedia
- Foreground service type to declare in manifest under
android:foregroundServiceTypemediaProjection- 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
MediaProjectionAPIs. This content doesn't have to be exclusively media content.- Alternatives
To stream media to another device, use the Google Cast SDK.
Micrófono
- Foreground service type to declare in manifest under
android:foregroundServiceTypemicrophone- 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_AUDIOruntime permission.Note: The
RECORD_AUDIOruntime permission is subject to while-in-use restrictions. For this reason, you cannot create amicrophoneforeground 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:foregroundServiceTypephoneCall- 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_CALLSpermission in its manifest file.
- App has declared the
- App is the default dialer app through the
ROLE_DIALERrole.
- App is the default dialer app through the
- Description
Continue an ongoing call using the
ConnectionServiceAPIs.- Alternatives
If you need to make phone, video, or VoIP calls, consider using the
android.telecomlibrary.Consider using
CallScreeningServiceto screen calls.
Mensajería remota
- Tipo de servicio en primer plano que se declarará en el manifiesto en
android:foregroundServiceTyperemoteMessaging- 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:foregroundServiceTypeshortService- 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_SERVICEpermission. - A
shortServicecan 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
shortServiceat 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
shortServiceis 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_SERVICEparameter 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
shortServicetype and another foreground service type, the system ignores theshortServicetype 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:foregroundServiceTypespecialUse- 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 usarspecialUseel 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:foregroundServiceTypesystemExempted- 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_ALARMoUSE_EXACT_ALARMy 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
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.