capacitor-android-shortcuts

capacitor-android-shortcuts

This plugin provides the feature to add dynamic and pinned shortcuts in Android apps. See more in the Android docs. Its possible to listen to a shortcut tap action with an event listener (see Usage).

Dynamic shortcut
Tap and hold on the app icon and you will see the dynamic shortcuts in the dropdown
=> Usage: Call the setDynamic method one time to set the array of dynamic shortcuts

Pinned shortcut
You can add a pinned shortcut programmatically inside your app, i.e. let a customer add a favorite of an article/product/... to the home screen
=> Usage: Call the pin method where the user wants to pin something. An alert will be shown to add the pinned shortcut to the home screen.

Supported platforms

Platform	Supported
Android	✔
iOS	✖
Web	✖

Install

npm install capacitor-android-shortcuts
npx cap sync android

Usage

import { AndroidShortcuts } from 'capacitor-android-shortcuts';

...

// Set dynamic shortcuts
AndroidShortcuts.isDynamicSupported().then(({ result }) => {
    if (result) {
        AndroidShortcuts.setDynamic({
            items: [
                {
                    id: "myfirstid",
                    shortLabel: "My first short label",
                    longLabel: "My first long label",
                    icon: {
                        type: "Bitmap",
                        name: "<base64-string>"
                    },
                    data: "I am a simple string",
                },
                {
                    id: "mysecondid",
                    shortLabel: "My first short label",
                    longLabel: "My first long label",
                    icon: {
                        type: "Resource",
                        name: "<vector-asset-name>"
                    },
                    data: JSON.stringify({
                        myProperty: "Pass a stringified JSON object",
                    }),
                },
            ],
        });
    }
});
...

// Add a pinned shortcut
AndroidShortcuts.isPinnedSupported().then(({ result }) => {
    if (result) {
        AndroidShortcuts.pin({
            id: "mypinnedid",
            shortLabel: "My pinned short label",
            longLabel: "My pinned long label",
            icon: {
                type: "Bitmap",
                name: "<base64-string>"
            },
            data: "I am a simple string",
        });
    }
});

// Triggered when app is launched by a shortcut
AndroidShortcuts.addListener('shortcut', (response: any) => {
  // response.data contains the content of the 'data' property of the created shortcut
});

Usage of icons

See Wiki: Icon examples

API

isDynamicSupported()

isDynamicSupported() => Promise<{ result: boolean; }>

Checks if dynamic shortcuts are supported on the device

Returns: Promise<{ result: boolean; }>

---

isPinnedSupported()

isPinnedSupported() => Promise<{ result: boolean; }>

Checks if pinned shortcuts are supported on the device

Returns: Promise<{ result: boolean; }>

---

setDynamic(...)

setDynamic(options: { items: ShortcutItem[]; }) => Promise<void>

Set dynamic shortcuts

Param	Type	Description
options	{ items: ShortcutItem[]; }	An items array with the options of each shortcut

---

pin(...)

pin(options: ShortcutItem) => Promise<void>

Add a pinned shortcut

Param	Type	Description
options	ShortcutItem	An option object for the pinned shortcut

---

addListener('shortcut', ...)

addListener(eventName: 'shortcut', listenerFunc: (response: { data: string; }) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Add a listener to a shortcut tap event

Param	Type
eventName	'shortcut'
listenerFunc	(response: { data: string; }) => void

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

---

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all listeners.

---

Interfaces

ShortcutItem

Prop	Type	Description
id	string	ID of the shortcut
shortLabel	string	Sets the short title of a shortcut. This is a mandatory field when publishing a new shortcut with ShortcutManager.addDynamicShortcuts(List) or ShortcutManager.setDynamicShortcuts(List). This field is intended to be a concise description of a shortcut. The recommended maximum length is 10 characters.
longLabel	string	Sets the text of a shortcut. This field is intended to be more descriptive than the shortcut title. The launcher shows this instead of the short title when it has enough space. The recommend maximum length is 25 characters.
icon	{ type: AvailableIconTypes; name: string; }	Defines the icon of the shortcut. You can set the icon as a BASE64-Bitmap or as a Resource name
data	string	Data that is passed to the 'shortcut' event

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Type Aliases

AvailableIconTypes

'Bitmap' | 'Resource'