---
description: Capacitor plugin to run a foreground service on Android. It allows apps to perform tasks in the background with notifications and manage overlay permissions.
title: Capacitor Android Foreground Service Plugin for Android - Capawesome
image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/android-foreground-service.png
---
[Skip to content ](#capacitor-android-foreground-service-plugin)
[π Introducing the **Capacitor Vault** plugin β store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/)
* [ SDKs ](/docs/sdks/)
* [ Configuration ](#configuration)
* [ Demo ](#demo)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ Enums ](#enums)
* [ FAQ ](#faq)
* [ Related Plugins ](#related-plugins)
* [ Newsletter ](#newsletter)
* [ Changelog ](#changelog)
* [ License ](#license)
* [ Android Intent Launcher ](/docs/sdks/capacitor/android-intent-launcher/)
* [ Android SMS Retriever ](/docs/sdks/capacitor/android-sms-retriever/)
* [ App Icon ](/docs/sdks/capacitor/app-icon/)
* [ App Integrity ](/docs/sdks/capacitor/app-integrity/)
* [ App Language ](/docs/sdks/capacitor/app-language/)
* [ App Launcher ](/docs/sdks/capacitor/app-launcher/)
* [ App Review ](/docs/sdks/capacitor/app-review/)
* [ App Shortcuts ](/docs/sdks/capacitor/app-shortcuts/)
* [ App Tracking Transparency ](/docs/sdks/capacitor/app-tracking-transparency/)
* [ App Update ](/docs/sdks/capacitor/app-update/)
* [ Apple Sign-In ](/docs/sdks/capacitor/apple-sign-in/)
* [ Asset Manager ](/docs/sdks/capacitor/asset-manager/)
* [ Audio Player ](/docs/sdks/capacitor/audio-player/)
* [ Audio Recorder ](/docs/sdks/capacitor/audio-recorder/)
* [ Audio Session ](/docs/sdks/capacitor/audio-session/)
* [ Background Task ](/docs/sdks/capacitor/background-task/)
* [ Badge ](/docs/sdks/capacitor/badge/)
* [ Barometer ](/docs/sdks/capacitor/barometer/)
* [ Battery ](/docs/sdks/capacitor/battery/)
* [ Biometrics ](/docs/sdks/capacitor/biometrics/)
* [ Bluetooth Low Energy ](/docs/sdks/capacitor/bluetooth-low-energy/)
* [ Clipboard ](/docs/sdks/capacitor/clipboard/)
* [ Cloudinary ](/docs/sdks/capacitor/cloudinary/)
* [ Compass ](/docs/sdks/capacitor/compass/)
* [ Contacts ](/docs/sdks/capacitor/contacts/)
* [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/)
* [ Device Info ](/docs/sdks/capacitor/device-info/)
* [ Dialog ](/docs/sdks/capacitor/dialog/)
* [ Exif ](/docs/sdks/capacitor/exif/)
* [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/)
* [ File Compressor ](/docs/sdks/capacitor/file-compressor/)
* [ File Opener ](/docs/sdks/capacitor/file-opener/)
* [ File Picker ](/docs/sdks/capacitor/file-picker/)
* [ Firebase ](/docs/sdks/capacitor/firebase/)
* [ Formbricks ](/docs/sdks/capacitor/formbricks/)
* [ Geocoder ](/docs/sdks/capacitor/geocoder/)
* [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/)
* [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/)
* [ Gyroscope ](/docs/sdks/capacitor/gyroscope/)
* [ Haptics ](/docs/sdks/capacitor/haptics/)
* [ Home Indicator ](/docs/sdks/capacitor/home-indicator/)
* [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/)
* [ Install Referrer ](/docs/sdks/capacitor/install-referrer/)
* [ Keep Awake ](/docs/sdks/capacitor/keep-awake/)
* [ libSQL ](/docs/sdks/capacitor/libsql/)
* [ Light Sensor ](/docs/sdks/capacitor/light-sensor/)
* [ Live Update ](/docs/sdks/capacitor/live-update/)
* [ Localization ](/docs/sdks/capacitor/localization/)
* [ Mail Composer ](/docs/sdks/capacitor/mail-composer/)
* [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/)
* [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/)
* [ Media Session ](/docs/sdks/capacitor/media-session/)
* [ ML Kit ](/docs/sdks/capacitor/mlkit/)
* [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/)
* [ Network ](/docs/sdks/capacitor/network/)
* [ NFC ](/docs/sdks/capacitor/nfc/)
* [ Node.js ](/docs/sdks/capacitor/nodejs/)
* [ OAuth ](/docs/sdks/capacitor/oauth/)
* [ Passkeys ](/docs/sdks/capacitor/passkeys/)
* [ Password Autofill ](/docs/sdks/capacitor/password-autofill/)
* [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/)
* [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/)
* [ Pedometer ](/docs/sdks/capacitor/pedometer/)
* [ Permissions ](/docs/sdks/capacitor/permissions/)
* [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/)
* [ Photo Editor ](/docs/sdks/capacitor/photo-editor/)
* [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/)
* [ PixLive ](/docs/sdks/capacitor/pixlive/)
* [ PostHog ](/docs/sdks/capacitor/posthog/)
* [ Printer ](/docs/sdks/capacitor/printer/)
* [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/)
* [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/)
* [ Purchases ](/docs/sdks/capacitor/purchases/)
* [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/)
* [ Root Detection ](/docs/sdks/capacitor/root-detection/)
* [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/)
* [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/)
* [ Screen Reader ](/docs/sdks/capacitor/screen-reader/)
* [ Screenshot ](/docs/sdks/capacitor/screenshot/)
* [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/)
* [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/)
* [ Shake ](/docs/sdks/capacitor/shake/)
* [ Silent Mode ](/docs/sdks/capacitor/silent-mode/)
* [ SIM ](/docs/sdks/capacitor/sim/)
* [ SMS Composer ](/docs/sdks/capacitor/sms-composer/)
* [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/)
* [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/)
* [ Share Target ](/docs/sdks/capacitor/share-target/)
* [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/)
* [ SQLite ](/docs/sdks/capacitor/sqlite/)
* [ Superwall ](/docs/sdks/capacitor/superwall/)
* [ System WebView ](/docs/sdks/capacitor/system-webview/)
* [ Text Interaction ](/docs/sdks/capacitor/text-interaction/)
* [ Text Zoom ](/docs/sdks/capacitor/text-zoom/)
* [ Thermal State ](/docs/sdks/capacitor/thermal-state/)
* [ Toast ](/docs/sdks/capacitor/toast/)
* [ Torch ](/docs/sdks/capacitor/torch/)
* [ Vault ](/docs/sdks/capacitor/vault/)
* [ Volume ](/docs/sdks/capacitor/volume/)
* [ Wallet ](/docs/sdks/capacitor/wallet/)
* [ Wifi ](/docs/sdks/capacitor/wifi/)
* [ Zip ](/docs/sdks/capacitor/zip/)
* [ Cordova ](/docs/sdks/cordova/)
* [ Cloud ](/docs/cloud/)
* [ Integrations ](/docs/cloud/live-updates/integrations/)
* Concepts
* Reference
* [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/)
* [ FAQ ](/docs/cloud/live-updates/faq/)
* [ Native Builds ](/docs/cloud/native-builds/)
* [ Set Up Environments ](/docs/cloud/native-builds/environments/)
* [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/)
* [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/)
* [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/)
* [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/)
* [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/)
* [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/)
* [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/)
* [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/)
* [ Build without Git ](/docs/cloud/native-builds/build-without-git/)
* [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/)
* [ Integrations ](/docs/cloud/native-builds/integrations/)
* Reference
* [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/)
* [ FAQ ](/docs/cloud/native-builds/faq/)
* [ App Store Publishing ](/docs/cloud/app-store-publishing/)
* [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/)
* [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/)
* [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/)
* [ FAQ ](/docs/cloud/app-store-publishing/faq/)
* [ Automations ](/docs/cloud/automations/)
* [ Reference ](/docs/cloud/automations/reference/)
* [ Troubleshooting ](/docs/cloud/automations/troubleshooting/)
* [ FAQ ](/docs/cloud/automations/faq/)
* [ Assist ](/docs/cloud/assist/)
* [ CLI ](/docs/cloud/cli/)
* APIs and SDKs
* [ Webhooks ](/docs/cloud/webhooks/)
* [ Integrations ](/docs/cloud/integrations/)
* Account
* [ Organization ](/docs/cloud/organizations/)
* [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/)
* [ Audit Logs ](/docs/cloud/organizations/audit-logs/)
* [ Billing ](/docs/cloud/organizations/billing/)
* [ License Keys ](/docs/cloud/license-keys/)
* [ AI ](/docs/ai/)
* [ Insiders ](/docs/insiders/)
* [ Billing & Plans ](/docs/insiders/billing-and-plans/)
* [ FAQ ](/docs/insiders/faq/)
* [ License ](https://capawesome.io/legal/eula/)
* [ Support ](/docs/support/)
* [ Contributing ](/docs/contributing/)
* Contributing code
* [ Code of Conduct ](/docs/contributing/code-of-conduct/)
* [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion)
* [ Blog ](/blog/)
* Categories
* [ Configuration ](#configuration)
* [ Demo ](#demo)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ Enums ](#enums)
* [ FAQ ](#faq)
* [ Related Plugins ](#related-plugins)
* [ Newsletter ](#newsletter)
* [ Changelog ](#changelog)
* [ License ](#license)
# Capacitor Android Foreground Service Plugin[ΒΆ](#capacitor-android-foreground-service-plugin "Permanent link")
Capacitor plugin to run a foreground service on Android.
[  ](https://cloud.capawesome.io/)
## Use Cases[ΒΆ](#use-cases "Permanent link")
The Android Foreground Service plugin is typically used whenever an app needs to keep running a task while it is in the background, for example:
* **Location tracking**: Run long-running use cases that require location access, such as navigation or location sharing, using the `Location` service type.
* **Audio recording**: Continue microphone capture from the background, such as voice recorders or communication apps, using the `Microphone` service type.
* **Long-running tasks with user awareness**: Show a persistent notification with a title, body, and icon while your app performs work in the background.
* **Interactive notifications**: Add buttons to the foreground service notification and react to them via the `buttonClicked` event.
* **Bringing the app back to the foreground**: Move the app to the foreground programmatically, for example in response to a notification button click.
## Compatibility[ΒΆ](#compatibility "Permanent link")
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | \>=8.x.x | Active support |
## Installation[ΒΆ](#installation "Permanent link")
You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
`[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins
`
Then use the following prompt:
`` [](#%5F%5Fcodelineno-1-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-android-foreground-service` plugin in my project.
``
If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
`[](#%5F%5Fcodelineno-2-1)npm install @capawesome-team/capacitor-android-foreground-service
[](#%5F%5Fcodelineno-2-2)npx cap sync
`
### Android[ΒΆ](#android "Permanent link")
This API requires the following permissions be added to your `AndroidManifest.xml` before or after the `application` tag:
`[](#%5F%5Fcodelineno-3-1)
[](#%5F%5Fcodelineno-3-2)
[](#%5F%5Fcodelineno-3-3)
[](#%5F%5Fcodelineno-3-4)
[](#%5F%5Fcodelineno-3-5)
[](#%5F%5Fcodelineno-3-6)
`
**Attention**: Replace `FOREGROUND_SERVICE_LOCATION` with the foreground service types you want to use (see [Foreground service types](https://developer.android.com/develop/background-work/services/fg-service-types)). See [ServiceType](#servicetype) for the available types.
You also need to add the following receiver and service **inside** the `application` tag in your `AndroidManifest.xml`:
`[](#%5F%5Fcodelineno-4-1)
[](#%5F%5Fcodelineno-4-2)
`
**Attention**: Replace `location` with the foreground service types you want to use (see [Foreground service types](https://developer.android.com/develop/background-work/services/fg-service-types)). See [ServiceType](#servicetype) for the available types.
## Configuration[ΒΆ](#configuration "Permanent link")
No configuration required for this plugin.
## Demo[ΒΆ](#demo "Permanent link")
A working example can be found here: [robingenz/capacitor-plugin-demo](https://github.com/robingenz/capacitor-plugin-demo)
| Android |
| --------------------------------------------------------------------------------------------------------------------------------------- |
|  |
## Usage[ΒΆ](#usage "Permanent link")
The following examples show how to start, update, and stop a foreground service and how to create and delete notification channels.
### Start a foreground service[ΒΆ](#start-a-foreground-service "Permanent link")
Start the foreground service with a persistent notification. You can optionally add buttons to the notification, which trigger the `buttonClicked` event when tapped. Only available on Android:
`[](#%5F%5Fcodelineno-5-1)import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';
[](#%5F%5Fcodelineno-5-2)
[](#%5F%5Fcodelineno-5-3)const startForegroundService = async () => {
[](#%5F%5Fcodelineno-5-4) await ForegroundService.startForegroundService({
[](#%5F%5Fcodelineno-5-5) id: 1,
[](#%5F%5Fcodelineno-5-6) title: 'Title',
[](#%5F%5Fcodelineno-5-7) body: 'Body',
[](#%5F%5Fcodelineno-5-8) smallIcon: 'ic_stat_icon_config_sample',
[](#%5F%5Fcodelineno-5-9) buttons: [
[](#%5F%5Fcodelineno-5-10) {
[](#%5F%5Fcodelineno-5-11) title: 'Button 1',
[](#%5F%5Fcodelineno-5-12) id: 1,
[](#%5F%5Fcodelineno-5-13) },
[](#%5F%5Fcodelineno-5-14) {
[](#%5F%5Fcodelineno-5-15) title: 'Button 2',
[](#%5F%5Fcodelineno-5-16) id: 2,
[](#%5F%5Fcodelineno-5-17) },
[](#%5F%5Fcodelineno-5-18) ],
[](#%5F%5Fcodelineno-5-19) silent: false,
[](#%5F%5Fcodelineno-5-20) notificationChannelId: 'default',
[](#%5F%5Fcodelineno-5-21) });
[](#%5F%5Fcodelineno-5-22)};
`
### Update the foreground service notification[ΒΆ](#update-the-foreground-service-notification "Permanent link")
Update the notification details of the running foreground service, for example to show the progress of a task. Only available on Android:
`[](#%5F%5Fcodelineno-6-1)import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';
[](#%5F%5Fcodelineno-6-2)
[](#%5F%5Fcodelineno-6-3)const updateForegroundService = async () => {
[](#%5F%5Fcodelineno-6-4) await ForegroundService.updateForegroundService({
[](#%5F%5Fcodelineno-6-5) id: 1,
[](#%5F%5Fcodelineno-6-6) title: 'Title',
[](#%5F%5Fcodelineno-6-7) body: 'Body',
[](#%5F%5Fcodelineno-6-8) smallIcon: 'ic_stat_icon_config_sample',
[](#%5F%5Fcodelineno-6-9) });
[](#%5F%5Fcodelineno-6-10)};
`
### Stop the foreground service[ΒΆ](#stop-the-foreground-service "Permanent link")
Stop the running foreground service when the background work is done. Only available on Android:
`[](#%5F%5Fcodelineno-7-1)import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';
[](#%5F%5Fcodelineno-7-2)
[](#%5F%5Fcodelineno-7-3)const stopForegroundService = async () => {
[](#%5F%5Fcodelineno-7-4) await ForegroundService.stopForegroundService();
[](#%5F%5Fcodelineno-7-5)};
`
### Create and delete notification channels[ΒΆ](#create-and-delete-notification-channels "Permanent link")
Create a notification channel for the foreground service notification. If not invoked, the plugin creates a channel with name and description set to "Default". Only available on Android (SDK 26+):
`[](#%5F%5Fcodelineno-8-1)import { ForegroundService, Importance } from '@capawesome-team/capacitor-android-foreground-service';
[](#%5F%5Fcodelineno-8-2)
[](#%5F%5Fcodelineno-8-3)const createNotificationChannel = async () => {
[](#%5F%5Fcodelineno-8-4) await ForegroundService.createNotificationChannel({
[](#%5F%5Fcodelineno-8-5) id: 'default',
[](#%5F%5Fcodelineno-8-6) name: 'Default',
[](#%5F%5Fcodelineno-8-7) description: 'Default channel',
[](#%5F%5Fcodelineno-8-8) importance: Importance.Default,
[](#%5F%5Fcodelineno-8-9) });
[](#%5F%5Fcodelineno-8-10)};
[](#%5F%5Fcodelineno-8-11)
[](#%5F%5Fcodelineno-8-12)const deleteNotificationChannel = async () => {
[](#%5F%5Fcodelineno-8-13) await ForegroundService.deleteNotificationChannel({
[](#%5F%5Fcodelineno-8-14) id: 'default',
[](#%5F%5Fcodelineno-8-15) });
[](#%5F%5Fcodelineno-8-16)};
`
## API[ΒΆ](#api "Permanent link")
* [moveToForeground()](#movetoforeground)
* [startForegroundService(...)](#startforegroundservice)
* [updateForegroundService(...)](#updateforegroundservice)
* [stopForegroundService()](#stopforegroundservice)
* [checkPermissions()](#checkpermissions)
* [requestPermissions()](#requestpermissions)
* [checkManageOverlayPermission()](#checkmanageoverlaypermission)
* [requestManageOverlayPermission()](#requestmanageoverlaypermission)
* [createNotificationChannel(...)](#createnotificationchannel)
* [deleteNotificationChannel(...)](#deletenotificationchannel)
* [addListener('buttonClicked', ...)](#addlistenerbuttonclicked-)
* [addListener('notificationTapped', ...)](#addlistenernotificationtapped-)
* [removeAllListeners()](#removealllisteners)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)
### moveToForeground()[ΒΆ](#movetoforeground "Permanent link")
`[](#%5F%5Fcodelineno-9-1)moveToForeground() => Promise
`
Moves the app to the foreground.
On Android SDK 23+, the user must grant the manage overlay permission. You can use the `requestManageOverlayPermission()` method to request the permission and the `checkManageOverlayPermission()` method to check if the permission is granted.
Only available on Android.
**Since:** 0.3.0
---
### startForegroundService(...)[ΒΆ](#startforegroundservice "Permanent link")
`[](#%5F%5Fcodelineno-10-1)startForegroundService(options: StartForegroundServiceOptions) => Promise
`
Starts the foreground service.
Only available on Android.
| Param | Type |
| ----------- | --------------------------------------------------------------- |
| **options** | [StartForegroundServiceOptions](#startforegroundserviceoptions) |
**Since:** 0.0.1
---
### updateForegroundService(...)[ΒΆ](#updateforegroundservice "Permanent link")
`[](#%5F%5Fcodelineno-11-1)updateForegroundService(options: UpdateForegroundServiceOptions) => Promise
`
Updates the notification details of the running foreground service.
Only available on Android.
| Param | Type |
| ----------- | --------------------------------------------------------------- |
| **options** | [StartForegroundServiceOptions](#startforegroundserviceoptions) |
**Since:** 6.1.0
---
### stopForegroundService()[ΒΆ](#stopforegroundservice "Permanent link")
`[](#%5F%5Fcodelineno-12-1)stopForegroundService() => Promise
`
Stops the foreground service.
Only available on Android.
**Since:** 0.0.1
---
### checkPermissions()[ΒΆ](#checkpermissions "Permanent link")
`[](#%5F%5Fcodelineno-13-1)checkPermissions() => Promise
`
Check permission to display notifications.
On **Android**, this method only needs to be called on Android 13+.
Only available on Android.
**Returns:** `Promise<[PermissionStatus](#permissionstatus)>`
**Since:** 5.0.0
---
### requestPermissions()[ΒΆ](#requestpermissions "Permanent link")
`[](#%5F%5Fcodelineno-14-1)requestPermissions() => Promise
`
Request permission to display notifications.
On **Android**, this method only needs to be called on Android 13+.
Only available on Android.
**Returns:** `Promise<[PermissionStatus](#permissionstatus)>`
**Since:** 5.0.0
---
### checkManageOverlayPermission()[ΒΆ](#checkmanageoverlaypermission "Permanent link")
`[](#%5F%5Fcodelineno-15-1)checkManageOverlayPermission() => Promise
`
Check if the overlay permission is granted.
Only available on Android.
**Returns:** `Promise<[ManageOverlayPermissionResult](#manageoverlaypermissionresult)>`
**Since:** 0.3.0
---
### requestManageOverlayPermission()[ΒΆ](#requestmanageoverlaypermission "Permanent link")
`[](#%5F%5Fcodelineno-16-1)requestManageOverlayPermission() => Promise
`
Request the manage overlay permission.
Only available on Android.
**Returns:** `Promise<[ManageOverlayPermissionResult](#manageoverlaypermissionresult)>`
**Since:** 0.3.0
---
### createNotificationChannel(...)[ΒΆ](#createnotificationchannel "Permanent link")
`[](#%5F%5Fcodelineno-17-1)createNotificationChannel(options: CreateNotificationChannelOptions) => Promise
`
Create a notification channel. If not invoked, the plugin creates a channel with name and description set to "Default".
Only available for Android (SDK 26+).
| Param | Type |
| ----------- | --------------------------------------------------------------------- |
| **options** | [CreateNotificationChannelOptions](#createnotificationchanneloptions) |
**Since:** 6.1.0
---
### deleteNotificationChannel(...)[ΒΆ](#deletenotificationchannel "Permanent link")
`[](#%5F%5Fcodelineno-18-1)deleteNotificationChannel(options: DeleteNotificationChannelOptions) => Promise
`
Delete a notification channel.
Only available for Android (SDK 26+).
| Param | Type |
| ----------- | --------------------------------------------------------------------- |
| **options** | [DeleteNotificationChannelOptions](#deletenotificationchanneloptions) |
**Since:** 6.1.0
---
### addListener('buttonClicked', ...)[ΒΆ](#addlistenerbuttonclicked "Permanent link")
`[](#%5F%5Fcodelineno-19-1)addListener(eventName: 'buttonClicked', listenerFunc: ButtonClickedEventListener) => Promise
`
Called when a notification button is clicked.
Only available on iOS.
| Param | Type |
| ---------------- | --------------------------------------------------------- |
| **eventName** | 'buttonClicked' |
| **listenerFunc** | [ButtonClickedEventListener](#buttonclickedeventlistener) |
**Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>`
**Since:** 0.2.0
---
### addListener('notificationTapped', ...)[ΒΆ](#addlistenernotificationtapped "Permanent link")
`[](#%5F%5Fcodelineno-20-1)addListener(eventName: 'notificationTapped', listenerFunc: NotificationTappedEventListener) => Promise
`
Called when the foreground service notification is tapped.
Only available on Android.
| Param | Type |
| ---------------- | ------------------------------------------------------------------- |
| **eventName** | 'notificationTapped' |
| **listenerFunc** | [NotificationTappedEventListener](#notificationtappedeventlistener) |
**Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>`
**Since:** 8.1.0
---
### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link")
`[](#%5F%5Fcodelineno-21-1)removeAllListeners() => Promise
`
Remove all listeners for this plugin.
**Since:** 0.2.0
---
### Interfaces[ΒΆ](#interfaces "Permanent link")
#### StartForegroundServiceOptions[ΒΆ](#startforegroundserviceoptions "Permanent link")
| Prop | Type | Description | Default | Since |
| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| **body** | string | The body of the notification, shown below the title. | | 0.0.1 |
| **buttons** | NotificationButton\[\] | The buttons to show on the notification. Only available on Android (SDK 24+). | | 0.2.0 |
| **id** | number | The notification identifier. | | 0.0.1 |
| **serviceType** | [ServiceType](#servicetype) | The foreground service type. Only available on Android (SDK 29+). | | 6.2.0 |
| **smallIcon** | string | The status bar icon for the notification. Icons should be placed in your app's res/drawable folder. The value for this option should be the drawable resource ID, which is the filename without an extension. | | 0.0.1 |
| **title** | string | The title of the notification. | | 0.0.1 |
| **silent** | boolean | If true, will only alert (sound/vibration) on the first notification. Subsequent updates will be silent. | false | 6.1.0 |
| **notificationChannelId** | string | The notification channel identifier. | | 6.1.0 |
#### NotificationButton[ΒΆ](#notificationbutton "Permanent link")
| Prop | Type | Description | Since |
| --------- | ------ | --------------------------------------------------------------------------------------------------- | ----- |
| **title** | string | The button title. | 0.2.0 |
| **id** | number | The button identifier. This is used to identify the button when the buttonClicked event is emitted. | 0.2.0 |
#### PermissionStatus[ΒΆ](#permissionstatus "Permanent link")
| Prop | Type | Description | Since |
| ----------- | ----------------------------------- | --------------------------------------------- | ----- |
| **display** | [PermissionState](#permissionstate) | Permission state of displaying notifications. | 5.0.0 |
#### ManageOverlayPermissionResult[ΒΆ](#manageoverlaypermissionresult "Permanent link")
| Prop | Type | Description | Since |
| ----------- | ------- | --------------------------------------------------------------------------- | ----- |
| **granted** | boolean | Whether the permission is granted. This is always true on Android SDK < 23. | 0.3.0 |
#### CreateNotificationChannelOptions[ΒΆ](#createnotificationchanneloptions "Permanent link")
| Prop | Type | Description | Since |
| --------------- | ------------------------- | ------------------------------------------------------------------- | ----- |
| **description** | string | The description of this channel (presented to the user). | 6.1.0 |
| **id** | string | The channel identifier. | 6.1.0 |
| **importance** | [Importance](#importance) | The level of interruption for notifications posted to this channel. | 6.1.0 |
| **name** | string | The name of this channel (presented to the user). | 6.1.0 |
#### DeleteNotificationChannelOptions[ΒΆ](#deletenotificationchanneloptions "Permanent link")
| Prop | Type | Description | Since |
| ------ | ------ | ----------------------- | ----- |
| **id** | string | The channel identifier. | 6.1.0 |
#### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link")
| Prop | Type |
| ---------- | ------------------- |
| **remove** | () => Promise |
#### ButtonClickedEvent[ΒΆ](#buttonclickedevent "Permanent link")
| Prop | Type | Description | Since |
| ------------ | ------ | ---------------------- | ----- |
| **buttonId** | number | The button identifier. | 0.2.0 |
#### NotificationTappedEvent[ΒΆ](#notificationtappedevent "Permanent link")
| Prop | Type | Description | Since |
| ------------------ | ------ | ---------------------------- | ----- |
| **notificationId** | number | The notification identifier. | 8.1.0 |
### Type Aliases[ΒΆ](#type-aliases "Permanent link")
#### UpdateForegroundServiceOptions[ΒΆ](#updateforegroundserviceoptions "Permanent link")
`[StartForegroundServiceOptions](#startforegroundserviceoptions)`
#### PermissionState[ΒΆ](#permissionstate "Permanent link")
`'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'`
#### ButtonClickedEventListener[ΒΆ](#buttonclickedeventlistener "Permanent link")
`(event: [ButtonClickedEvent](#buttonclickedevent)): void`
#### NotificationTappedEventListener[ΒΆ](#notificationtappedeventlistener "Permanent link")
`(event: [NotificationTappedEvent](#notificationtappedevent)): void`
### Enums[ΒΆ](#enums "Permanent link")
#### ServiceType[ΒΆ](#servicetype "Permanent link")
| Members | Value | Description | Since |
| -------------- | ----- | ----------------------------------------------------------------------------------------------- | ----- |
| **Location** | 8 | Long-running use cases that require location access, such as navigation and location sharing. | 6.2.0 |
| **Microphone** | 128 | Continue microphone capture from the background, such as voice recorders or communication apps. | 6.2.0 |
#### Importance[ΒΆ](#importance "Permanent link")
| Members | Value | Since |
| ----------- | ----- | ----- |
| **Min** | 1 | 6.1.0 |
| **Low** | 2 | 6.1.0 |
| **Default** | 3 | 6.1.0 |
| **High** | 4 | 6.1.0 |
| **Max** | 5 | 6.1.0 |
## FAQ[ΒΆ](#faq "Permanent link")
### Why can the user dismiss the notification?[ΒΆ](#why-can-the-user-dismiss-the-notification "Permanent link")
Android 14 has changed the behavior to allow users to dismiss such notifications, see [Changes to how users experience non-dismissible notifications](https://developer.android.com/about/versions/14/behavior-changes-all#non-dismissable-notifications).
### Which permissions does this plugin require?[ΒΆ](#which-permissions-does-this-plugin-require "Permanent link")
You need to add the `FOREGROUND_SERVICE` permission along with the permission for each foreground service type you use (for example `FOREGROUND_SERVICE_LOCATION`) to your `AndroidManifest.xml`, see the [Installation](#installation) section. On Android 13+, you should also use `checkPermissions()` and `requestPermissions()` to request the permission to display notifications.
### Why does `moveToForeground` not work?[ΒΆ](#why-does-movetoforeground-not-work "Permanent link")
On Android SDK 23+, the user must grant the manage overlay permission before the app can be moved to the foreground. Use the `requestManageOverlayPermission()` method to request the permission and the `checkManageOverlayPermission()` method to check whether it has been granted.
### Which foreground service types are supported?[ΒΆ](#which-foreground-service-types-are-supported "Permanent link")
The plugin currently supports the `Location` service type for long-running use cases that require location access and the `Microphone` service type for continued microphone capture from the background. Make sure to declare the matching permission and the `android:foregroundServiceType` attribute in your `AndroidManifest.xml`, see the [Installation](#installation) section.
### Does this plugin work on iOS or Web?[ΒΆ](#does-this-plugin-work-on-ios-or-web "Permanent link")
No, this plugin only provides an Android implementation, as the name suggests. Foreground services are an Android concept and all methods are only available on Android.
## Related Plugins[ΒΆ](#related-plugins "Permanent link")
* [Background Task](https://capawesome.io/docs/sdks/capacitor/background-task/): Run background tasks in your Capacitor app.
* [Android Battery Optimization](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions on Android.
* [Keep Awake](https://capawesome.io/docs/sdks/capacitor/keep-awake/): Keep the screen awake while your app is in use.
## Newsletter[ΒΆ](#newsletter "Permanent link")
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
## Changelog[ΒΆ](#changelog "Permanent link")
See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/CHANGELOG.md).
## License[ΒΆ](#license "Permanent link")
See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/android-foreground-service/LICENSE).
July 8, 2026
Back to top
```json
{"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/#article", "headline": "Capacitor Android Foreground Service Plugin for Android", "name": "Capacitor Android Foreground Service Plugin for Android", "description": "Capacitor plugin to run a foreground service on Android. It allows apps to perform tasks in the background with notifications and manage overlay permissions.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/#software", "name": "Capacitor Android Foreground Service Plugin for Android", "description": "Capacitor plugin to run a foreground service on Android. It allows apps to perform tasks in the background with notifications and manage overlay permissions.", "url": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]}
{"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Why can the user dismiss the notification?", "acceptedAnswer": {"@type": "Answer", "text": "Android 14 has changed the behavior to allow users to dismiss such notifications, see Changes to how users experience non-dismissible notifications."}}, {"@type": "Question", "name": "Which permissions does this plugin require?", "acceptedAnswer": {"@type": "Answer", "text": "You need to add the FOREGROUND_SERVICE permission along with the permission for each foreground service type you use (for example FOREGROUND_SERVICE_LOCATION) to your AndroidManifest.xml, see the Installation section. On Android 13+, you should also use checkPermissions() and requestPermissions() to request the permission to display notifications."}}, {"@type": "Question", "name": "Why does moveToForeground not work?", "acceptedAnswer": {"@type": "Answer", "text": "On Android SDK 23+, the user must grant the manage overlay permission before the app can be moved to the foreground. Use the requestManageOverlayPermission() method to request the permission and the checkManageOverlayPermission() method to check whether it has been granted."}}, {"@type": "Question", "name": "Which foreground service types are supported?", "acceptedAnswer": {"@type": "Answer", "text": "The plugin currently supports the Location service type for long-running use cases that require location access and the Microphone service type for continued microphone capture from the background. Make sure to declare the matching permission and the android:foregroundServiceType attribute in your AndroidManifest.xml, see the Installation section."}}, {"@type": "Question", "name": "Does this plugin work on iOS or Web?", "acceptedAnswer": {"@type": "Answer", "text": "No, this plugin only provides an Android implementation, as the name suggests. Foreground services are an Android concept and all methods are only available on Android."}}], "url": "https://capawesome.io/docs/sdks/capacitor/android-foreground-service/"}
```