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

Capacitor plugin to run a foreground service on Android.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills

Then use the following prompt:

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:

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" />
<!-- Required to keep the app running in the background without any ressource limitations -->
<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). See ServiceType for the available 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). See ServiceType for the available 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',
  });
};

API

• moveToForeground()
• startForegroundService(...)
• updateForegroundService(...)
• stopForegroundService()
• checkPermissions()
• requestPermissions()
• checkManageOverlayPermission()
• requestManageOverlayPermission()
• createNotificationChannel(...)
• deleteNotificationChannel(...)
• addListener('buttonClicked', ...)
• addListener('notificationTapped', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

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

updateForegroundService(...)

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

Updates the notification details of the running foreground service.

Only available on Android.

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+).

Since: 6.1.0

deleteNotificationChannel(...)

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

Delete a notification channel.

Only available for Android (SDK 26+).

Since: 6.1.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

addListener('notificationTapped', ...)

addListener(eventName: 'notificationTapped', listenerFunc: NotificationTappedEventListener) => Promise<PluginListenerHandle>

Called when the foreground service notification is tapped.

Only available on Android.

Returns: Promise<PluginListenerHandle>

Since: 8.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.2.0

Interfaces

StartForegroundServiceOptions

NotificationButton

PermissionStatus

ManageOverlayPermissionResult

CreateNotificationChannelOptions

DeleteNotificationChannelOptions

PluginListenerHandle

ButtonClickedEvent

NotificationTappedEvent

Type Aliases

UpdateForegroundServiceOptions

StartForegroundServiceOptions

PermissionState

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

ButtonClickedEventListener

(event: ButtonClickedEvent): void

NotificationTappedEventListener

(event: NotificationTappedEvent): void

Enums

ServiceType

Importance

FAQ

Why can the user dismiss the notification?

Android 14 has changed the behavior to allow users to dismiss such notifications, see Changes to how users experience non-dismissible notifications.

Changelog

See CHANGELOG.md.

License

See LICENSE.