@capawesome-team/capacitor-android-foreground-service v6.0.1

@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.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Required to request the manage overlay permission -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

Attention: Replace FOREGROUND_SERVICE_LOCATION with the foreground service types you want to use (see Foreground service types).

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" android:foregroundServiceType="location" />

Attention: Replace location with the foreground service types you want to use (see Foreground service types).

Configuration

No configuration required for this plugin.

Demo

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

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

Since: 0.3.0

startForegroundService(...)

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

Starts the foreground service.

Only available on Android.

Since: 0.0.1

stopForegroundService()

stopForegroundService() => Promise<void>

Stops the foreground service.

Only available on 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 on 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 on Android.

Returns: Promise<PermissionStatus>

Since: 5.0.0

checkManageOverlayPermission()

checkManageOverlayPermission() => Promise<ManageOverlayPermissionResult>

Check if the overlay permission is granted.

Only available on Android.

Returns: Promise<ManageOverlayPermissionResult>

Since: 0.3.0

requestManageOverlayPermission()

requestManageOverlayPermission() => Promise<ManageOverlayPermissionResult>

Request the manage overlay permission.

Only available on Android.

Returns: Promise<ManageOverlayPermissionResult>

Since: 0.3.0

addListener('buttonClicked', ...)

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

Called when a notification button is clicked.

Only available on iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.2.0

Interfaces

StartForegroundServiceOptions

NotificationButton

PermissionStatus

ManageOverlayPermissionResult

PluginListenerHandle

ButtonClickedEvent

Type Aliases

PermissionState

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

ButtonClickedEventListener

(event: ButtonClickedEvent): void

Changelog

See CHANGELOG.md.

License

See LICENSE.