Share via


Service.StartForeground Method

Definition

Overloads

StartForeground(Int32, Notification)

If your service is started (running through Context#startService(Intent)), then also make this service run in the foreground, supplying the ongoing notification to be shown to the user while in this state.

StartForeground(Int32, Notification, ForegroundService)

An overloaded version of #startForeground(int, Notification) with additional foregroundServiceType parameter.

StartForeground(Int32, Notification)

If your service is started (running through Context#startService(Intent)), then also make this service run in the foreground, supplying the ongoing notification to be shown to the user while in this state.

[Android.Runtime.Register("startForeground", "(ILandroid/app/Notification;)V", "")]
public void StartForeground (int id, Android.App.Notification? notification);
[<Android.Runtime.Register("startForeground", "(ILandroid/app/Notification;)V", "")>]
member this.StartForeground : int * Android.App.Notification -> unit

Parameters

id
Int32

The identifier for this notification as per NotificationManager#notify(int, Notification) NotificationManager.notify(int, Notification); must not be 0.

notification
Notification

The Notification to be displayed.

Attributes

Remarks

If your service is started (running through Context#startService(Intent)), then also make this service run in the foreground, supplying the ongoing notification to be shown to the user while in this state. By default started services are background, meaning that their process won't be given foreground CPU scheduling (unless something else in that process is foreground) and, if the system needs to kill them to reclaim more memory (such as to display a large page in a web browser), they can be killed without too much harm. You use #startForeground if killing your service would be disruptive to the user, such as if your service is performing background music playback, so the user would notice if their music stopped playing.

Note that calling this method does <em>not</em> put the service in the started state itself, even though the name sounds like it. You must always call #startService(Intent) first to tell the system it should keep the service running, and then use this method to tell it to keep it running harder.

Apps targeting API android.os.Build.VERSION_CODES#P or later must request the permission android.Manifest.permission#FOREGROUND_SERVICE in order to use this API.

Apps built with SDK version android.os.Build.VERSION_CODES#Q or later can specify the foreground service types using attribute android.R.attr#foregroundServiceType in service element of manifest file. The value of attribute android.R.attr#foregroundServiceType can be multiple flags ORed together.

<div class="caution">

<strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#S, apps targeting SDK Version android.os.Build.VERSION_CODES#S or higher are not allowed to start foreground services from the background. See Behavior changes: Apps targeting Android 12 for more details. </div>

<div class="caution">

<strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, apps targeting SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE or higher are not allowed to start foreground services without specifying a valid foreground service type in the manifest attribute android.R.attr#foregroundServiceType. See Behavior changes: Apps targeting Android 14 for more details. </div>

Java documentation for android.app.Service.startForeground(int, android.app.Notification).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

See also

Applies to

StartForeground(Int32, Notification, ForegroundService)

An overloaded version of #startForeground(int, Notification) with additional foregroundServiceType parameter.

[Android.Runtime.Register("startForeground", "(ILandroid/app/Notification;I)V", "", ApiSince=29)]
public void StartForeground (int id, Android.App.Notification notification, Android.Content.PM.ForegroundService foregroundServiceType);
[<Android.Runtime.Register("startForeground", "(ILandroid/app/Notification;I)V", "", ApiSince=29)>]
member this.StartForeground : int * Android.App.Notification * Android.Content.PM.ForegroundService -> unit

Parameters

id
Int32

The identifier for this notification as per NotificationManager#notify(int, Notification) NotificationManager.notify(int, Notification); must not be 0.

notification
Notification

The Notification to be displayed.

foregroundServiceType
ForegroundService

must be a subset flags of manifest attribute android.R.attr#foregroundServiceType flags; must not be ServiceInfo#FOREGROUND_SERVICE_TYPE_NONE.

Attributes

Remarks

An overloaded version of #startForeground(int, Notification) with additional foregroundServiceType parameter.

Apps built with SDK version android.os.Build.VERSION_CODES#Q or later can specify the foreground service types using attribute android.R.attr#foregroundServiceType in service element of manifest file. The value of attribute android.R.attr#foregroundServiceType can be multiple flags ORed together.

The foregroundServiceType parameter must be a subset flags of what is specified in manifest attribute android.R.attr#foregroundServiceType, if not, an IllegalArgumentException is thrown. Specify foregroundServiceType parameter as android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_MANIFEST to use all flags that is specified in manifest attribute foregroundServiceType.

<div class="caution">

<strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#S, apps targeting SDK Version android.os.Build.VERSION_CODES#S or higher are not allowed to start foreground services from the background. See Behavior changes: Apps targeting Android 12 for more details. </div>

<div class="caution">

<strong>Note:</strong> Beginning with SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, apps targeting SDK Version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE or higher are not allowed to start foreground services without specifying a valid foreground service type in the manifest attribute android.R.attr#foregroundServiceType, and the parameter foregroundServiceType here must not be the ServiceInfo#FOREGROUND_SERVICE_TYPE_NONE. See Behavior changes: Apps targeting Android 14 for more details. </div>

Java documentation for android.app.Service.startForeground(int, android.app.Notification, int).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Applies to