@capawesome/capacitor-app-shortcuts

Capacitor plugin to manage app shortcuts and quick actions.

Installation

npm install @capawesome/capacitor-app-shortcuts
npx cap sync

Configuration

| Prop | Type | Description | Since | | --------------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----- | | shortcuts | Shortcut[] | The list of app shortcuts that should be set by default. Only available on Android and iOS. | 7.2.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "AppShortcuts": {
      "shortcuts": [{ id: 'feedback', title: 'Feedback' }]
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-app-shortcuts" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    AppShortcuts: {
      shortcuts: [{ id: 'feedback', title: 'Feedback' }],
    },
  },
};

export default config;

iOS

On iOS, you must add the following to your app's AppDelegate.swift:

+ import CapawesomeCapacitorAppShortcuts

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        if let shortcutItem = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
+            NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+            return true
+        }
        return true
    }
    
+    func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
+        NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+        completionHandler(true)
+    }

Demo

A working example can be found here.

| Android | iOS | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | | |

Usage

import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const clear = async () => {
  await AppShortcuts.clear();
};

const get = async () => {
  const result = await AppShortcuts.get();
  return result.shortcuts;
};

const set = async () => {
  await AppShortcuts.set({
    shortcuts: [
      {
        id: 'feedback',
        title: 'Feedback',
        description: 'Send us your feedback',
      },
      {
        id: 'rate',
        title: 'Rate',
        description: 'Rate our app',
      }
    ],
  });
};

const addListener = async () => {
  AppShortcuts.addListener('click', (event) => {
    console.log('Shortcut clicked:', event.id);
  });
};

API

• clear()
• get()
• set(...)
• addListener('click', ...)
• removeAllListeners()
• Interfaces

clear()

clear() => Promise<void>

Remove all app shortcuts.

Only available on Android and iOS.

Since: 6.0.0

get()

get() => Promise<GetResult>

Get all app shortcuts.

Only available on Android and iOS.

Returns: Promise<GetResult>

Since: 6.0.0

set(...)

set(options: SetOptions) => Promise<void>

Create or update app shortcuts.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------- | | options | SetOptions |

Since: 6.0.0

addListener('click', ...)

addListener(eventName: 'click', listenerFunc: (event: ClickEvent) => void) => Promise<PluginListenerHandle>

Called when an app shortcut is clicked.

Only available on Android and iOS.

| Param | Type | | ------------------ | --------------------------------------------------------------------- | | eventName | 'click' | | listenerFunc | (event: ClickEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 6.0.0

Interfaces

GetResult

| Prop | Type | Description | Since | | --------------- | ----------------------- | -------------------------- | ----- | | shortcuts | Shortcut[] | The list of app shortcuts. | 6.0.0 |

Shortcut

| Prop | Type | Description | Since | | ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | description | string | The description. On Android, the launcher shows this instead of the short title when it has enough space. Attention: On iOS, the icon and the description must be used together. | 6.0.0 | | id | string | The unique identifier. | 6.0.0 | | title | string | The display name. | 6.0.0 | | icon | string | number | The icon to display. On Android, the icon can be one of the following: - An integer value of the R.drawable enum (e.g. 17301547). - A string that represents the name of the drawable resource (e.g. "alert_dark_frame"). - A base64 encoded image string (e.g. "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."). On iOS, the icon can be one of the following: - The constant integer value of the UIApplicationShortcutIcon.IconType enum (e.g. 6). - A system symbol name (e.g. star.fill). - Name of the image asset from the asset catalogue. | 6.1.0 | | androidIcon | string | number | The icon to display on Android. The icon can be one of the following: - An integer value of the R.drawable enum (e.g. 17301547). - A string that represents the name of the drawable resource (e.g. "alert_dark_frame"). - A base64 encoded image string (e.g. "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."). | 7.2.0 | | iosIcon | string | number | The icon to display on iOS. The icon can be one of the following: - The constant integer value of the UIApplicationShortcutIcon.IconType enum (e.g. 6). - A system symbol name (e.g. star.fill). - Name of the image asset from the asset catalogue. | 7.2.0 |

SetOptions

| Prop | Type | Description | Since | | --------------- | ----------------------- | -------------------------- | ----- | | shortcuts | Shortcut[] | The list of app shortcuts. | 6.0.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ClickEvent

| Prop | Type | Description | Since | | ---------------- | ------------------- | ----------------------------------------------------------- | ----- | | shortcutId | string | The unique identifier of the app shortcut that was clicked. | 6.0.0 |

Changelog

See CHANGELOG.md.

License

See LICENSE.