6.0.2 • Published 8 months ago

capacitor-fullscreen-notification v6.0.2

Weekly downloads
-
License
MIT
Repository
github
Last release
8 months ago

npm version capacitor support

capacitor-fullscreen-notification

This plugin can automatically launch your app, triggered by a data push notification by the @capacitor/push-notifications plugin.

Use case example: Someone rings your doorbell -> your app opens and navigates to a specific route

Supported platforms

PlatformSupported
Android
iOS
Web

Install

npm install capacitor-fullscreen-notification
npx cap sync android

Add this to the activity inside your AndroidManifest.xml:

android:showWhenLocked="true"
android:turnScreenOn="true"

Android behavior

The Android OS differs between an locked and unlocked device.

Locked

The app will only be launched instantly, when your device is in standby.

Unlocked

If your device is not in standby, you will get a default heads up notification with the defined title, text and actionButtons. When you click on it, the app will launch.

HINT\ To identify if the app has been launched instantly or by clicking the heads up notification, you can check the property 'isNotificationActive' in the response data of your 'launch' listener. This is true on instant launch.

HINT: Android 14 and above\ Starting with Android 14, the full screen intent permission must be granted manually by the user after each update, if the app does not provide calling and alarm functionalities.\ More info: https://source.android.com/docs/core/permissions/fsi-limits

Workflow

This plugin will start a fullscreen intent by a local notification, when it receives a specific data push notification.

Firebase
1. Send a data push
Plugin
2. Receives the data push
3. Sends a local notification with full screen intent (opens app)
4. Emits a plugin event
App
5. Listen to event and redirect to any page

Usage

Trigger push

Send a data push notification (leave the field notification empty!) with the following key value pairs in the data option:

OptionDescription
fullScreenId(Required) Identifier of the fullscreen notification
channelIdIdentifier of the notification channel
channelNameName of the notification channel
channelDescriptionDescription of the notification channel
titleTitle of the heads up notification
textText of the heads up notification
timeoutTimeout, for auto removing the notification
vibrationPatternStringified array of long values (docs)
actionButtonsStringified array of ActionButton objects

ActionButton

PropDescription
idIdentifier of the button
textButton text

Example

{
  "fullScreenId": "my-fullscreen-identifier",
  "channelId": "fullscreen-channel",
  "channelName": "My Fullscreen Channel",
  "channelDescription": "Notifications in this channel will be displayed with a fullscreen intent",
  "title": "Test notification",
  "text": "Test description",
  "timeout": "10000",
  "vibrationPattern": "[500, 300, 500, 300, 500, 300, 500, 300]",
  "actionButtons": "[{ \"id\": \"reject\", \"text\": \"Reject\" }, { \"id\": \"accept\", \"text\": \"Accept\" }]"
}

App

In your app, you can listen to the launch of the application. This event is fired when the fullscreen notification opens or the heads up notification is clicked. You can also cancel the active notification, if it exists:

import { FullScreenNotification } from 'capacitor-fullscreen-notification';

FullScreenNotification.addListener('launch', (data) => {
    ...
});

...

await FullScreenNotification.cancelNotification();

Inside the data of the launch event, you can have the following data:

PropTypeDescription
fullScreenIdstringIdentifier of the triggering request
isNotificationActivebooleanIs the notification still active
timeoutnumber(Optionally) Timeout value of the triggering request
actionIdstring(Optionally) Idenfifier of the clicked action button

API

cancelNotification()

cancelNotification() => any

Cancel the current notification

Returns: any


canUseFullScreenIntent()

canUseFullScreenIntent() => any

Check if the user granted permission to show full screen intents

Returns: any


openFullScreenIntentSettings()

openFullScreenIntentSettings() => any

Open the settings page to grant the full screen permission

Returns: any


addListener('launch', ...)

addListener(eventName: 'launch', listenerFunc: MessageListener) => any

Add a listener when the fullscreen intent launches the app. You can navigate here to the destination page. The parameter gives you the information if an action button has been clicked.

ParamType
eventName'launch'
listenerFuncMessageListener

Returns: any


removeAllListeners()

removeAllListeners() => any

Removes all listeners.

Returns: any


Interfaces

PluginListenerHandle

PropType
remove() => any

Type Aliases

MessageListener

(response: any): void

6.0.2

8 months ago

6.0.2-dev.1

8 months ago

6.0.1

12 months ago

6.0.0

12 months ago

5.0.3

2 years ago

5.0.2

2 years ago

5.0.1

2 years ago

5.0.0

2 years ago

4.0.5

3 years ago

4.0.4

3 years ago

4.0.1

3 years ago

4.0.0

3 years ago

4.0.3

3 years ago

4.0.2

3 years ago

1.0.3

3 years ago

1.0.2

4 years ago

1.0.1

4 years ago

1.0.0

4 years ago