Skip to content

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

Capacitor plugin to run a foreground service on Android.

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 inside 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.

Demo

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

Android

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()

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.