{"id":15141962,"url":"https://github.com/eddyverbruggen/nativescript-app-shortcuts","last_synced_at":"2025-10-23T19:30:57.113Z","repository":{"id":9180633,"uuid":"61057901","full_name":"EddyVerbruggen/nativescript-app-shortcuts","owner":"EddyVerbruggen","description":":point_down: Home Icon Actions for your NativeScript app, now also for Android!","archived":false,"fork":false,"pushed_at":"2023-01-14T01:05:39.000Z","size":4873,"stargazers_count":48,"open_issues_count":18,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-30T20:30:35.291Z","etag":null,"topics":["3d-touch","3dtouch","app-shortcuts","nativescript","nativescript-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EddyVerbruggen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-13T17:56:23.000Z","updated_at":"2024-05-30T15:51:27.000Z","dependencies_parsed_at":"2023-01-14T12:00:46.483Z","dependency_job_id":null,"html_url":"https://github.com/EddyVerbruggen/nativescript-app-shortcuts","commit_stats":null,"previous_names":["eddyverbruggen/nativescript-3dtouch"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-app-shortcuts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-app-shortcuts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-app-shortcuts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-app-shortcuts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-app-shortcuts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237877021,"owners_count":19380344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-touch","3dtouch","app-shortcuts","nativescript","nativescript-plugin"],"created_at":"2024-09-26T09:21:10.331Z","updated_at":"2025-10-23T19:30:56.479Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NativeScript Icon Shortcuts plugin\n\n[![Build Status][build-status]][build-url]\n[![NPM version][npm-image]][npm-url]\n[![Downloads][downloads-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[build-status]:https://travis-ci.org/EddyVerbruggen/nativescript-app-shortcuts.svg?branch=master\n[build-url]:https://travis-ci.org/EddyVerbruggen/nativescript-app-shortcuts\n[npm-image]:http://img.shields.io/npm/v/nativescript-app-shortcuts.svg\n[npm-url]:https://npmjs.org/package/nativescript-app-shortcuts\n[downloads-image]:http://img.shields.io/npm/dm/nativescript-app-shortcuts.svg\n[twitter-image]:https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social\u0026label=Follow%20me\n[twitter-url]:https://twitter.com/eddyverbruggen\n\n\u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-app-shortcuts/master/media/iOS.png\" width=\"360px\" /\u003e  \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-app-shortcuts/master/media/Android.png\" width=\"360px\" /\u003e\n\n### Supported platforms\n* iPhone 6s / 6s Plus or newer, running iOS 9 or newer.\n* Android 7.1 (API level 25) or newer.\n\n## Installation\nFrom the command prompt go to your app's root folder and execute:\n\nNativesScript 7.x\n```\ntns plugin add nativescript-app-shortcuts\n```\n\nNativesScript 6.x\n```\ntns plugin add nativescript-app-shortcuts@2.2.0\n```\n\n## Demo app (XML \u0026 TypeScript)\nWant to dive in quickly? Check out [the demo app](demo)! Otherwise, continue reading.\n\n## Demo app (Angular)\nThis plugin is part of the [plugin showcase app](https://github.com/EddyVerbruggen/nativescript-pluginshowcase/tree/master/app/appicon) I built using Angular.\n\n## API\n\n### `available`\nCheck whether or not the device is capable.\nAndroid devices will also report `false`, so you can use this cross platform.\n\n##### JavaScript\n```js\n// require the plugin\nvar AppShortcuts = require(\"nativescript-app-shortcuts\").AppShortcuts;\n\n// instantiate the plugin\nvar appShortcuts = new AppShortcuts();\n\nappShortcuts.available().then(\n  function(available) {\n    if (available) {\n      console.log(\"This device supports app shortcuts\");\n    } else {\n      console.log(\"No app shortcuts capability, ask the user to upgrade :)\");\n    }\n  }\n);\n```\n\n##### TypeScript\n```typescript\n// require the plugin\nimport { AppShortcuts } from \"nativescript-app-shortcuts\";\n\n// instantiate the plugin\nlet appShortcuts = new AppShortcuts();\n\nappShortcuts.available().then(available =\u003e {\n  if (available) {\n    console.log(\"This device supports app shortcuts\");\n  } else {\n    console.log(\"No app shortcuts capability, ask the user to upgrade :)\");\n  }\n});\n```\n\n### `configureQuickActions`\nWhen your app is running you can add those fancy Quick Actions to the Home Screen icon. You can configure up to four icons and they are 'cached' by iOS until you pass in a new set of icons. So you don't need to do this every time your app loads, but it can't really hurt of course.\n\nThe `type` param (see the code sample below) is the most convenient way to relate the icon to the event you'll receive when the action was used to launch your app. So make sure it's unique amongst your icons.\n\nThere are two types of icons currently supported: `iconType` and `iconTemplate`.\n\n#### iconType (iOS)\nA value from a [fixed list of icons which have been provided by Apple](https://developer.apple.com/ios/human-interface-guidelines/icons-and-images/system-icons/#home-screen-quick-action-icons) and look great (click the value in the 'API' column to look up the Objective-C name, and look at the sample below how to use them).\n\n#### iconTemplate\nCan be used to provide your own icon. It must be a valid name of an icon template in your Assets catalog. NativeScript allows you to add the icon to the `app/App_Resources/\u003cplatform\u003e` folder. If you add a file called `beer.png` then reference it as `beer`. More on these images below when we discuss static actions.\n\nIgnored on iOS, if `iconType` is set as well.\n\n##### TypeScript\n```typescript\nimport { AppShortcuts } from \"nativescript-app-shortcuts\";\nimport { isIOS } from \"tns-core-modules/platform\";\n\nlet appShortcuts = new AppShortcuts();\n\nappShortcuts.configureQuickActions([\n  {\n    type: \"capturePhoto\",\n    title: \"Snag a pic\",\n    subtitle: \"You have 23 snags left\", // iOS only\n    iconType: isIOS ? UIApplicationShortcutIconType.CapturePhoto : null,\n    iconTemplate: \"eye\" // ignored by iOS, if iconType is set as well\n  },\n  {\n    type: \"beer\",\n    title: \"Beer-tastic!\",\n    subtitle: \"Check in \u0026 share\", // iOS only\n    iconTemplate: \"beer\"\n  }\n]).then(() =\u003e {\n  alert(\"Added 2 actions, close the app and apply pressure to the app icon to check it out!\");\n}, (errorMessage) =\u003e {\n  alert(errorMessage);\n});\n```\n\n## Capturing the Action\nWhen a home icon is pressed, your app launches. You probably want to perform different actions based on the home icon action\nthat was picked (like routing to a different page), so you need a way to capture the event.\n\n### NativeScript with XML\nIn a non-Angular NativeScript app we need to extend `app.js` or `app.ts` and import the plugin,\nthen call the `setQuickActionCallback` function. So in case of `app.ts` change it from something like this:\n\n```typescript\nimport * as application from \"tns-core-modules/application\";\napplication.start({ moduleName: \"main-page\" });\n```\n\nTo this:\n\n```typescript\nimport * as application from \"tns-core-modules/application\";\n\n// import the plugin\nimport { AppShortcuts } from \"nativescript-app-shortcuts\";\n\n// instantiate it and call setQuickActionCallback\nnew AppShortcuts().setQuickActionCallback(shortcutItem =\u003e {\n  console.log(`The app was launched by shortcut type '${shortcutItem.type}'`);\n\n  // this is where you handle any specific case for the shortcut\n  if (shortcutItem.type === \"beer\") {\n    // this is an example of 'deeplinking' through a shortcut\n    let frames = require(\"ui/frame\");\n    // on Android we need a little delay\n    setTimeout(() =\u003e {\n      frames.topmost().navigate(\"beer-page\");\n    });\n  } else {\n    // .. any other shortcut handling\n  }\n});\n\napplication.start({ moduleName: \"main-page\" });\n```\n\n### NativeScript with Angular\nIf you're using Angular, the best place to add the handler is in `app.module.ts`,\nand use `NgZone` to help Angular knowing about the route change you're performing:\n\n```typescript\nimport { NgZone } from \"@angular/core\";\nimport { isIOS } from \"tns-core-modules/platform\";\nimport { RouterExtensions } from \"nativescript-angular\";\nimport { AppShortcuts } from \"nativescript-app-shortcuts\";\n\nexport class AppModule {\n  constructor(private routerExtensions: RouterExtensions,\n              private zone: NgZone) {\n\n    new AppShortcuts().setQuickActionCallback(shortcutItem =\u003e {\n  console.log(`The app was launched by shortcut type '${shortcutItem.type}'`);\n\n      // this is where you handle any specific case for the shortcut, based on its type\n      if (shortcutItem.type === \"page1\") {\n        this.deeplink(\"/page1\");\n      } else if (shortcutItem.type === \"page2\") {\n        this.deeplink(\"/page2\");\n      }\n    });\n  }\n\n  private deeplink(to: string): void {\n    this.zone.run(() =\u003e {\n      this.routerExtensions.navigate([to], {\n        animated: false\n      });\n    });\n  }\n}\n```\n\n## Configuring Static Actions\nWith `configureQuickActions` you can configure dynamic actions,\nbut what if you want actions to be available immediately after the app as installed from the store?\n\n### iOS\nYou need to manually edit the `.plist`.\nFortunately NativeScript allows you to change this file through `app/App_Resources/iOS/Info.plist`. Anything added there is added to the final `.plist` during a build.\n\nNote that dynamic actions will never replace static actions, so if you have two static actions you can add up to two dynamic ones. Any more will be ignored.\n\nHere's an example which you can paste anywhere in the `.plist` file:\n\n```xml\n\u003ckey\u003eUIApplicationShortcutItems\u003c/key\u003e\n\u003carray\u003e\n  \u003cdict\u003e\n    \u003ckey\u003eUIApplicationShortcutItemIconFile\u003c/key\u003e\n    \u003cstring\u003eEye\u003c/string\u003e\n    \u003ckey\u003eUIApplicationShortcutItemTitle\u003c/key\u003e\n    \u003cstring\u003eEye from plist\u003c/string\u003e\n    \u003ckey\u003eUIApplicationShortcutItemSubtitle\u003c/key\u003e\n    \u003cstring\u003eAwesome subtitle\u003c/string\u003e\n    \u003ckey\u003eUIApplicationShortcutItemType\u003c/key\u003e\n    \u003cstring\u003eeyefromplist\u003c/string\u003e\n  \u003c/dict\u003e\n  \u003cdict\u003e\n    \u003ckey\u003eUIApplicationShortcutItemIconType\u003c/key\u003e\n    \u003cstring\u003eUIApplicationShortcutIconTypeCompose\u003c/string\u003e\n    \u003ckey\u003eUIApplicationShortcutItemTitle\u003c/key\u003e\n    \u003cstring\u003eCompose\u003c/string\u003e\n    \u003ckey\u003eUIApplicationShortcutItemType\u003c/key\u003e\n    \u003cstring\u003ecompose\u003c/string\u003e\n  \u003c/dict\u003e\n\u003c/array\u003e\n```\n\n#### UIApplicationShortcutItemIconFile\n\nThe second action above uses the built-in `UIApplicationShortcutIconTypeCompose` icon, but the first one uses a custom icon: `Eye`. This expects the file `app/App_Resources/iOS/Eye.png`. According to Apple's docs this needs to be a single color, transparent, square, `35x35` icon - but that size will look pixelated on retina devices so go ahead and use a `70x70` or `105x105` icon if you please.\n\n#### UIApplicationShortcutItemTitle / UIApplicationShortcutItemSubtitle\n\nYou can guess what those do, right? Only the title is mandatory.\n\n#### UIApplicationShortcutItemType\n\nThis is the same as the `type` param of `configureQuickActions`, so it's what you'll receive in the callback you may have configured in `app.js` / `app.ts`  as `payload.type`. Just do something cool with that info (like routing to a specific page and loading some content).\n\n### Android\nOpen `app/App_Resources/Android/AndroidManifest.xml` and add:\n\n```xml\n\u003cactivity ..\u003e \u003c!-- your existing NativeScript activity --\u003e\n  \u003cmeta-data android:name=\"android.app.shortcuts\"\n             android:resource=\"@xml/shortcuts\" /\u003e\n\u003c/activity\u003e\n```\n\nAdd the file you referenced in `AndroidManifest.xml`: `/app/App_Resources/Android/xml/shortcuts.xml` and add:\n\n```xml\n\u003cshortcuts xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n  \u003cshortcut\n      android:shortcutId=\"compose\"\n      android:enabled=\"true\"\n      android:icon=\"@drawable/add\"\n      android:shortcutShortLabel=\"@string/shortcut_short_label1\"\n      android:shortcutLongLabel=\"@string/shortcut_long_label1\"\n      android:shortcutDisabledMessage=\"@string/shortcut_disabled_message1\"\u003e\n    \u003cintent\n        android:action=\"shortcut.type.compose\"\n        android:targetPackage=\"org.nativescript.plugindemo.appshortcuts\"\n        android:targetClass=\"com.tns.NativeScriptActivity\"/\u003e\n    \u003ccategories android:name=\"android.shortcut.conversation\"/\u003e\n  \u003c/shortcut\u003e\n\u003c/shortcuts\u003e\n```\n\nA few notes:\n- This adds 1 static `shortcut` to your app (you can add more if you like).\n- Make sure the `action` has the `shortcut.type.` prefix. The value behind the prefix is the equivalent of the iOS `UIApplicationShortcutItemType`.\n- The `targetPackage` needs to be your app id.\n- The `targetClass` needs to be the `activity` class as mentioned in `AndroidManifest.xml`, which is `com.tns.NativeScriptApplication` by default. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-app-shortcuts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-app-shortcuts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-app-shortcuts/lists"}