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

Capacitor plugin to run a foreground service on Android.

Installation¶

npm install @capawesome-team/capacitor-android-foreground-service
npx cap sync

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

Android

Usage¶

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

const startForegroundService = async () => {
  await ForegroundService.startForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
    buttons: [
      {
        title: 'Button 1',
        id: 1,
      },
      {
        title: 'Button 2',
        id: 2,
      },
    ],
    silent: false,
    notificationChannelId: 'default',
  });
};

const updateForegroundService = async () => {
  await ForegroundService.updateForegroundService({
    id: 1,
    title: 'Title',
    body: 'Body',
    smallIcon: 'ic_stat_icon_config_sample',
  });
};

const stopForegroundService = async () => {
  await ForegroundService.stopForegroundService();
};

const createNotificationChannel = async () => {
  await ForegroundService.createNotificationChannel({
    id: 'default',
    name: 'Default',
    description: 'Default channel',
    importance: Importance.Default,
  });
};

const deleteNotificationChannel = async () => {
  await ForegroundService.deleteNotificationChannel({
    id: 'default',
  });
};

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.

Param	Type
`options`	`StartForegroundServiceOptions`

Since: 0.0.1

updateForegroundService(...)¶

updateForegroundService(options: UpdateForegroundServiceOptions) => Promise<void>

Updates the notification details of the running foreground service.

Only available on Android.

Param	Type
`options`	`StartForegroundServiceOptions`

Since: 6.1.0

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

createNotificationChannel(...)¶

createNotificationChannel(options: CreateNotificationChannelOptions) => Promise<void>

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`

Since: 6.1.0

deleteNotificationChannel(...)¶

deleteNotificationChannel(options: DeleteNotificationChannelOptions) => Promise<void>

Delete a notification channel.

Only available for Android (SDK 26+).

Param	Type
`options`	`DeleteNotificationChannelOptions`

Since: 6.1.0

addListener('buttonClicked', ...)¶

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

Called when a notification button is clicked.

Only available on iOS.

Param	Type
`eventName`	`'buttonClicked'`
`listenerFunc`	`ButtonClickedEventListener`

Returns: Promise<PluginListenerHandle>

Since: 0.2.0

removeAllListeners()¶

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.2.0

Interfaces¶

StartForegroundServiceOptions¶

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
`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¶

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

CreateNotificationChannelOptions¶

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`	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¶

Prop	Type	Description	Since
`id`	`string`	The channel identifier.	6.1.0

PluginListenerHandle¶

Prop	Type
`remove`	`() => Promise<void>`

ButtonClickedEvent¶

Prop	Type	Description	Since
`buttonId`	`number`	The button identifier.	0.2.0

Type Aliases¶

UpdateForegroundServiceOptions¶

StartForegroundServiceOptions

PermissionState¶

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

ButtonClickedEventListener¶

(event: ButtonClickedEvent): void

Enums¶

Importance¶

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

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.