Foreground services perform operations that are noticeable to the user.
Each foreground service must show a status bar
notification that has a priority of
PRIORITY_LOW
or higher. That way, users are actively aware that your app is performing a task
in the foreground and is consuming system resources. The notification cannot be
dismissed unless the service is either stopped or removed from the foreground.
If an app tries to use a status bar notification whose priority is lower than
PRIORITY_LOW
,
the system adds a message to the notification drawer, alerting the user to the
app's use of a foreground service.
Examples of apps that would use foreground services include the following:
- A music player app that plays music in a foreground service. The notification might show the current song that is being played.
- A fitness app that records a user's run in a foreground service, after receiving permission from the user. The notification might show the distance that the user has traveled during the current fitness session.
You should only use a foreground service when your app needs to perform a task that is noticeable by the user even when they're not directly interacting with the app. If the action is of low enough importance that you want to use a minimum-priority notification, create a background task instead.
This document describes the required permission for using foreground services, how to start a foreground service and remove it from the background, how to associate certain use cases with foreground service types, and the access restrictions that take effect when you start a foreground service from an app that's running in the background.
Request the foreground service permission
Apps that target Android 9 (API level 28) or higher and use foreground services
must request the
FOREGROUND_SERVICE
permission, as shown in the following code snippet. This is a normal
permission, so the system
automatically grants it to the requesting app.
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...> <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/> <application ...> ... </application> </manifest>
Start a foreground service
To request that your service run in the foreground, call startForeground()
. This method takes two
parameters: a positive integer that uniquely identifies the notification in the status bar and the
Notification
object itself. The notification must
have a priority of PRIORITY_LOW
or higher. Here is an
example:
Kotlin
val pendingIntent: PendingIntent = Intent(this, ExampleActivity::class.java).let { notificationIntent -> PendingIntent.getActivity(this, 0, notificationIntent, 0) } val notification: Notification = Notification.Builder(this, CHANNEL_DEFAULT_IMPORTANCE) .setContentTitle(getText(R.string.notification_title)) .setContentText(getText(R.string.notification_message)) .setSmallIcon(R.drawable.icon) .setContentIntent(pendingIntent) .setTicker(getText(R.string.ticker_text)) .build() // Notification ID cannot be 0. startForeground(ONGOING_NOTIFICATION_ID, notification)
Java
Intent notificationIntent = new Intent(this, ExampleActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); Notification notification = new Notification.Builder(this, CHANNEL_DEFAULT_IMPORTANCE) .setContentTitle(getText(R.string.notification_title)) .setContentText(getText(R.string.notification_message)) .setSmallIcon(R.drawable.icon) .setContentIntent(pendingIntent) .setTicker(getText(R.string.ticker_text)) .build(); // Notification ID cannot be 0. startForeground(ONGOING_NOTIFICATION_ID, notification);
Remove a service from the foreground
To remove the service from the foreground, call
stopForeground()
.
This method takes a boolean, which indicates whether to remove the status bar
notification as well. Note that the service continues to run.
If you stop the service while it's running in the foreground, its notification is removed.
Declare foreground service types
If your app targets Android 10 (API level 29) or higher and accesses location
information in a foreground service, declare the location
foreground service
type as an attribute of your <service>
component.
If your app targets Android 11 (API level 30) or higher and accesses the camera
or microphone in a foreground service, declare the camera
or microphone
foreground service types, respectively, as attributes of your <service>
component.
By default, when you call
startForeground()
at runtime, the system allows access to each of the service types that you
declare in the app manifest. You can choose to limit access to a subset of the
declared service types, as shown in the code snippets within the following
sections.
Example using location and camera
If a foreground service in your app needs to access the device's location and camera, declare the service as shown in the following snippet:
AndroidManifest.xml
<manifest> ... <service ... android:foregroundServiceType="location|camera" /> </manifest>
At runtime, if the foreground service only needs access to a subset of the types declared in the manifest, you can limit the service's access using the logic in the following code snippet:
MyService
Kotlin
val notification: Notification = ...; Service.startForeground(notification, FOREGROUND_SERVICE_TYPE_LOCATION)
Java
Notification notification = ...; Service.startForeground(notification, FOREGROUND_SERVICE_TYPE_LOCATION);
Example using location, camera, and microphone
If a foreground service needs to access location, the camera, and the microphone, declare the service as shown in the following snippet:
AndroidManifest.xml
<manifest> ... <service ... android:foregroundServiceType="location|camera|microphone" /> </manifest>
At runtime, if the foreground service only needs access to a subset of the types declared in the manifest, you can limit the service's access using the logic in the following code snippet:
MyService
Kotlin
val notification: Notification = ...; Service.startForeground(notification, FOREGROUND_SERVICE_TYPE_LOCATION or FOREGROUND_SERVICE_TYPE_CAMERA)
Java
Notification notification = ...; Service.startForeground(notification, FOREGROUND_SERVICE_TYPE_LOCATION | FOREGROUND_SERVICE_TYPE_CAMERA);
Add foreground service types of Work Manager workers
If your app uses Work Manager and has a long-running worker that requires access to location, camera, or microphone, follow the steps to add a foreground service type to a long-running worker, and specify the additional or alternative foreground service types that your worker uses. You can choose from the following foreground service types:
Restricted access to location, camera, and microphone
To help protect user privacy, Android 11 (API level 30) introduces limitations to when a foreground service can access the device's location, camera, or microphone. The limitations depend on the app's state when the service starts.
Restrictions applied to services that start while an app is running in the background
On Android 11 and higher, if your app starts a foreground service while the app is running in the background, the service has the following access restrictions:
- Unless the user has granted the
ACCESS_BACKGROUND_LOCATION
permission to your app, the service cannot access location. - The service cannot access the microphone or camera.
Exemptions from the restrictions
In some situations, even if a foreground service is started while the app is
running
in the background, it can still access location,
camera, and microphone information while the app is running in the foreground
("while-in-use"). In these same situations, if the service declares a
foreground service type of location
and is started by an app that
has the
ACCESS_BACKGROUND_LOCATION
permission, this service can access location information all the time, even when
the app is running in the background.
The following list contains these situations:
- The service is started by a system component.
- The service is started by interacting with app widgets.
- The service is started by interacting with a notification.
- The service is started as a
PendingIntent
that is sent from a different, visible app. - The service is started by an app that is a device policy controller that is running in device owner mode.
- The service is started by an app which provides the
VoiceInteractionService
. - The service is started by an app that has the
START_ACTIVITIES_FROM_BACKGROUND
privileged permission.
Restrictions applied to services that start while an app is running in the foreground
If your app starts a foreground service while the app is running in the foreground ("while-in-use"), the service has the following access restrictions:
- If the user has granted the
ACCESS_BACKGROUND_LOCATION
permission to your app, the service can access location all the time. Otherwise, if the user has granted theACCESS_FINE_LOCATION
orACCESS_COARSE_LOCATION
permission to your app, the service has access to location only while the app is running in the foreground (also known as "while-in-use access to location"). - If the user has granted the
CAMERA
permission to your app, the service can access the camera only while the app is running in the foreground. - If the user has granted the
RECORD_AUDIO
permission to your app, the service can access the microphone only while the app is running in the foreground.
Determine which services are affected in your app
When testing your app, start its foreground services. If a started service has restricted access to location, microphone, and camera, the following message appears in Logcat:
Foreground service started from background can not have \ location/camera/microphone access: service SERVICE_NAME