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() => any

Checks if dynamic shortcuts are supported on the device

Returns: any

isPinnedSupported()

isPinnedSupported() => any

Checks if pinned shortcuts are supported on the device

Returns: any

setDynamic(...)

setDynamic(options: { items: ShortcutItem[]; }) => any

Set dynamic shortcuts

| Param | Type | Description | | ------------- | --------------------------- | ------------------------------------------------ | | options | { items: {}; } | An items array with the options of each shortcut |

Returns: any

pin(...)

pin(options: ShortcutItem) => any

Add a pinned shortcut

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

Returns: any

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: any

removeAllListeners()

removeAllListeners() => any

Removes all listeners.

Returns: any

addDynamic(...)

addDynamic(options: { items: ShortcutItem[]; }) => any

DEPRECATED - Use setDynamic

| Param | Type | Description | | ------------- | --------------------------- | ------------------------------------------------ | | options | { items: {}; } | An items array with the options of each shortcut |

Returns: any

addPinned(...)

addPinned(options: ShortcutItem) => any

DEPRECATED - Use pin

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

Returns: any

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 | () => any |

Type Aliases

AvailableIconTypes

'Bitmap' | 'Resource'