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 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.
Declare new permission to use foreground service types
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.
Include foreground service type at runtime
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.
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.
System runtime checks
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.
Intended use cases and enforcement for each foreground service type
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.
Camera
Foreground service type to declare in manifest under android:foregroundServiceType
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.
Data sync
Foreground service type to declare in manifest under
Note: In order to check that the user has enabled location services
as well as granted access to the runtime permissions, use
PermissionChecker#checkSelfPermission()
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.
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 call
Service.stopSelf() or Service.stopForeground() before the
timeout occurs. Otherwise, the new Service.onTimeout() is called, giving
apps a brief opportunity to call stopSelf() or stopForeground() 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 mentions FOREGROUND_SERVICE_TYPE_SHORT_SERVICE. For these
reasons, it's considered best practice to implement the
Service.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 the Service.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 the
FOREGROUND_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 a
ForegroundServiceStartNotAllowedException.
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 the shortService type
declaration. However, the service must still adhere to the prerequisites of
the other declared types. For more information, see the Foreground services
documentation.
Special use
Foreground service type to declare in manifest under
Covers any valid foreground service use cases that aren't covered by the other
foreground service types.
In addition to declaring the FOREGROUND_SERVICE_TYPE_SPECIAL_USE
foreground service type, developers should declare use cases in the
manifest. To do so, they specify the <property> element within the
<service> element. These values and corresponding use cases are
reviewed when you submit your app in the Google Play Console. The use
cases you provide are free-form, and you should make sure to provide enough
information to let the reviewer see why you need to use the specialUse
type.
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.
Google Play policy enforcement for using foreground service types
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.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-01-28 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-01-28 UTC."],[],[]]
