Android Shortcuts Plugin for Cordova
DESCRIPTION
Use this plugin to create shortcuts in Android. Use this plugin to handle Intents on your application.
For more information on Android App Shortcuts: https://developer.android.com/guide/topics/ui/shortcuts.html
For more information on Android Intents: https://developer.android.com/guide/components/intents-filters.html
The work that went into creating this plug-in was inspired by the existing plugins: cordova-plugin-shortcut and cordova-plugin-webintent2.
How to install it
cordova plugins add @red-mobile/cordova-plugin-shortcuts-android
How to uninstall it
cordova plugin remove cordova-plugin-shortcuts-android
npm unisntall @red-mobile/cordova-plugin-shortcuts-android
How to use it
Checking if Dynamic Shortcuts are supported
Dynamic shortcuts require SDK 25 or later. Use supportsDynamic
to check whether the current device meets those requirements.
window.plugins.Shortcuts.supportsDynamic(function(supported) {
if (supported)
window.alert('Dynamic shortcuts are supported');
else
window.alert('Dynamic shortcuts are NOT supported');
}, function(error) {
window.alert('Error: ' + error);
})
Checking if Pinned Shortcuts are supported
Pinned shortcuts require SDK 26 or later. Use supportsPinned
to check whether the current device meets those requirements.
window.plugins.Shortcuts.supportsPinned(function(supported) {
if (supported)
window.alert('Pinned shortcuts are supported');
else
window.alert('Pinned shortcuts are NOT supported');
}, function(error) {
window.alert('Error: ' + error);
})
Setting the application Dynamic Shortcuts
Use setDynamic
to set the Dynamic Shortcuts for the application, all at once. The shortcuts provided as a parameter will override any existing shortcut. Use an empty array to clear out existing shortcuts.
var shortcut = {
id: 'my_shortcut_1',
shortLabel: 'Short description',
longLabel: 'Longer string describing the shortcut',
iconBitmap: '<Bitmap for the shortcut icon, base64 encoded>',
iconFromResource: "ic_playlist_play_red", //filename w/o extension of an icon that resides on res/drawable-* (hdpi,mdpi..)
intent: {
action: 'android.intent.action.RUN',
categories: [
'android.intent.category.TEST', // Built-in Android category
'MY_CATEGORY' // Custom categories are also supported
],
flags: 67108864, // FLAG_ACTIVITY_CLEAR_TOP
data: 'myapp://path/to/launch?param=value', // Must be a well-formed URI
extras: {
'android.intent.extra.SUBJECT': 'Hello world!', // Built-in Android extra (string)
'MY_BOOLEAN': true, // Custom extras are also supported (boolean, number and string only)
}
}
}
window.plugins.Shortcuts.setDynamic([shortcut], function() {
window.alert('Shortcuts were applied successfully');
}, function(error) {
window.alert('Error: ' + error);
})
Adding a Pinned Shortcut to the launcher
Use addPinned
to add a new Pinned Shortcut to the launcher.
var shortcut = {
id: 'my_shortcut_1',
shortLabel: 'Short description',
longLabel: 'Longer string describing the shortcut',
iconBitmap: '<Bitmap for the shortcut icon, base64 encoded>', // Defaults to the main application icon
iconFromResource: "ic_playlist_play_red", //filename w/o extension of an icon that resides on res/drawable-* (hdpi,mdpi..)
intent: {
action: 'android.intent.action.RUN',
categories: [
'android.intent.category.TEST', // Built-in Android category
'MY_CATEGORY' // Custom categories are also supported
],
flags: 67108864, // FLAG_ACTIVITY_CLEAR_TOP
data: 'myapp://path/to/launch?param=value', // Must be a well-formed URI
extras: {
'android.intent.extra.SUBJECT': 'Hello world!', // Built-in Android extra (string)
'MY_BOOLEAN': true, // Custom extras are also supported (boolean, number and string only)
}
}
}
window.plugins.Shortcuts.addPinned(shortcut, function() {
window.alert('Shortcut pinned successfully');
}, function(error) {
window.alert('Error: ' + error);
})
Querying current Intent
Use getIntent
to get the Intent that was used to launch the current instance of the Cordova activity.
window.plugins.Shortcuts.getIntent(function(intent) {
window.alert(JSON.stringify(intent));
})
Subscribe to new Intents
Use onNewIntent
to register a callback to be executed every time a new Intent is sent to your Cordova activity. Note that in some conditions this callback may not be executed.
For more information see the documentation for Activity.onNewIntent(Intent)
window.plugins.Shortcuts.onNewIntent(function(intent) {
window.alert(JSON.stringify(intent));
})
Call with an empty callback to de-register the existing callback.
window.plugins.Shortcuts.onNewIntent(); // De-register existing callback