⚠️ Deprecated repository

This project has been moved to the following monorepo: capawesome-team/capacitor-plugins.

---

Android Foreground Service

@capawesome-team/capacitor-android-foreground-service

Capacitor plugin to run a foreground service on Android.

Maintainers

Maintainer	GitHub	Social
Robin Genz	robingenz	@robin_genz

Sponsorware

This project is available as Sponsorware.

Sponsorware is a release strategy for open-source software that enables developers to be compensated for their open-source work with fewer downsides than traditional open-source funding models. (Source)

This means...

• The source code will be published as soon as our GitHub Sponsors goal is reached.
• Any GitHub sponsor with a sponsorware tier gets immediate access to our sponsors-only repository and can start using the project right away.

Terms

This project is licensed under the terms of the MIT license.
However, we kindly ask you to respect our fair use policy:

• Please don't distribute the source code of the sponsors-only repository. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy.
• If you cancel your subscription, you're automatically removed as a collaborator and will miss out on all future updates. However, you may use the latest version that's available to you as long as you like.

Demo

A working example can be found here: robingenz/capacitor-plugin-demo

Android

FAQ

1. Which platforms are supported?
   This plugin supports Android.
2. Which Capacitor versions are supported?
   This plugin supports Capacitor 4.
3. What do I do when I have a feature request?
   Please submit your feature request here. We will then review it and possibly put it on our roadmap.
4. What do I do when I have found a bug?
   Bug reports have top priority. Please submit your bug report here. We will take a look at it as soon as possible.

Installation

See Getting started with Insiders and follow the instructions to install the plugin.

After that, follow the platform-specific instructions in the section Android.

Android

This API requires the following permissions be added to your AndroidManifest.xml before or after the application tag:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required to request the manage overlay permission -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

You also need to add the following receiver and service in the application tag in your AndroidManifest.xml:

<receiver android:name="io.capawesome.capacitorjs.plugins.foregroundservice.NotificationActionBroadcastReceiver" />
<service android:name="io.capawesome.capacitorjs.plugins.foregroundservice.AndroidForegroundService" />

Configuration

No configuration required for this plugin.

Usage

import { Capacitor } from '@capacitor/core';
import { ForegroundService } from '@capawesome-team/capacitor-android-foreground-service';

const startForegroundService = async () => {
  if (Capacitor.getPlatform() !== 'android') {
    return false;
  }
  await ForegroundService.startForegroundService();
};

const stopForegroundService = async () => {
  if (Capacitor.getPlatform() !== 'android') {
    return false;
  }
  await ForegroundService.stopForegroundService();
};

API

• moveToForeground()
• startForegroundService(...)
• stopForegroundService()
• checkPermissions()
• requestPermissions()
• checkManageOverlayPermission()
• requestManageOverlayPermission()
• addListener('buttonClicked', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

moveToForeground()

moveToForeground() => Promise<void>

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 for Android.

Since: 0.3.0

---

startForegroundService(...)

startForegroundService(options: StartForegroundServiceOptions) => Promise<void>

Starts the foreground service.

Only available for Android.

Param	Type
options	StartForegroundServiceOptions

Since: 0.0.1

---

stopForegroundService()

stopForegroundService() => Promise<void>

Stops the foreground service.

Only available for Android.

Since: 0.0.1

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permission to display notifications.

On Android, this method only needs to be called on Android 13+.

Only available for Android.

Returns: Promise<PermissionStatus>

Since: 5.0.0

---

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to display notifications.

On Android, this method only needs to be called on Android 13+.

Only available for Android.

Returns: Promise<PermissionStatus>

Since: 5.0.0

---

checkManageOverlayPermission()

checkManageOverlayPermission() => Promise<ManageOverlayPermissionResult>

Check if the overlay permission is granted.

Only available for Android.

Returns: Promise<ManageOverlayPermissionResult>

Since: 0.3.0

---

requestManageOverlayPermission()

requestManageOverlayPermission() => Promise<ManageOverlayPermissionResult>

Request the manage overlay permission.

Only available for Android.

Returns: Promise<ManageOverlayPermissionResult>

Since: 0.3.0

---

addListener('buttonClicked', ...)

addListener(eventName: 'buttonClicked', listenerFunc: ButtonClickedEventListener) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when a notification button is clicked.

Only available on iOS.

Param	Type
eventName	'buttonClicked'
listenerFunc	ButtonClickedEventListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 0.2.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.2.0

---

Interfaces

StartForegroundServiceOptions

Prop	Type	Description	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 for Android (SDK 24+).	0.2.0
id	number	The notification identifier.	0.0.1
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

NotificationButton

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

Prop	Type	Description	Since
display	PermissionState	Permission state of displaying notifications.	5.0.0

ManageOverlayPermissionResult

Prop	Type	Description	Since
granted	boolean	Whether the permission is granted. This is always true on Android SDK < 23.	0.3.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

ButtonClickedEvent

Prop	Type	Description	Since
buttonId	number	The button identifier.	0.2.0

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ButtonClickedEventListener

(event: ButtonClickedEvent): void

Changelog

See CHANGELOG.md.

License

See LICENSE.