This Cordova plugin provides a general purpose shim layer for the Android intent mechanism, exposing various ways to handle sending and receiving intents.
This project uses code released under the following MIT projects:
- https://github.com/napolitano/cordova-plugin-intent (marked as no longer maintained)
- https://github.com/Initsogar/cordova-webintent.git (no longer available on github but the project is forked here: https://github.com/darryncampbell/cordova-webintent)
- https://github.com/darryncampbell/darryncampbell-cordova-plugin-intent
This project is also released under MIT. Credit is given in the code where appropriate
This plugin defines a window.plugins.intentShim object which provides an API for interacting with the Android intent mechanism on any Android device.
- Android
Registers a broadcast receiver for the specified filters
window.plugins.intentShim.registerBroadcastReceiver(filters, callback);
The intentShim.registerBroadcastReceiver function registers a dynamic broadcast receiver for the specified list of filters and invokes the specified callback when any of those filters are received
Any existing broadcast receiver is unregistered when this method is called. To register for multiple types of broadcast, specify multiple filters.
Register a broadcast receiver for two filters:
window.plugins.intentShim.registerBroadcastReceiver({
filterActions: [
'com.darryncampbell.cordova.plugin.broadcastIntent.ACTION',
'com.darryncampbell.cordova.plugin.broadcastIntent.ACTION_2'
]
},
function(intent) {
console.log('Received broadcast intent: ' + JSON.stringify(intent.extras));
}
);
Unregisters the broadcast receiver
window.plugins.intentShim.unregisterBroadcastReceiver();
The intentShim.unregisterBroadcastReceiver function unregisters the broadcast receiver registered with intentShim.registerBroadcastReceiver(filters, callback);. No further broadcasts will be received for any registered filter after this call.
The developer is responsible for calling unregister / register when their application goes into the background or comes back to the foreground, if desired.
Unregister the broadcast receiver when the application receives an onPause event:
bindEvents: function() {
document.addEventListener('pause', this.onPause, false);
},
onPause: function()
{
window.plugins.intentShim.unregisterBroadcastReceiver();
}
Sends a broadcast intent
window.plugins.intentShim.sendBroadcast(action, extras, successCallback, failureCallback);
The intentShim.sendBroadcast function sends an Android broadcast intent with a specified action
Send a broadcast intent to a specified action that contains a random number in the extras
window.plugins.intentShim.startActivity(
{
action: "com.darryncampbell.cordova.plugin.intent.ACTION",
extras: {
'random.number': Math.floor((Math.random() * 1000) + 1)
}
},
function() {},
function() {alert('Failed to open URL via Android Intent')}
);
Returns the content of the intent used whenever the application activity is launched
window.plugins.intentShim.onIntent(callback);
The intentShim.onIntent function returns the intent which launched the Activity and maps to the Android Activity's onNewIntent() method, https://developer.android.com/reference/android/app/Activity.html#onNewIntent(android.content.Intent). The registered callback is invoked whenever the activity is launched
By default the android application will be created with launch mode set to 'SingleTop'. If you wish to change this to 'SingleTask' you can do so by modifying config.xml as follows:
<platform name="android">
...
<preference name="AndroidLaunchMode" value="singleTask"/>
</platform>
See https://www.mobomo.com/2011/06/android-understanding-activity-launchmode/ for more information on the differences between the two.
Registers a callback to be invoked
window.plugins.intentShim.onIntent(function (intent) {
console.log('Received Intent: ' + JSON.stringify(intent.extras));
});
Starts a new activity using an intent built from action, url, type, extras or some subset of those parameters
window.plugins.intentShim.startActivity(params, successCallback, failureCallback);
The intentShim.startActivity function maps to Android's activity method startActivity, https://developer.android.com/reference/android/app/Activity.html#startActivity(android.content.Intent) to launch a new activity.
Some common actions are defined as constants in the plugin, see below.
Launch the maps activity
window.plugins.intentShim.startActivity(
{
action: window.plugins.intentShim.ACTION_VIEW,
url: 'geo:0,0?q=London'
},
function() {},
function() {alert('Failed to open URL via Android Intent')}
);
Launch the web browser
window.plugins.intentShim.startActivity(
{
action: window.plugins.intentShim.ACTION_VIEW,
url: 'http://www.google.co.uk'
},
function() {},
function() {alert('Failed to open URL via Android Intent')}
);
Retrieves the intent that launched the activity
window.plugins.intentShim.getIntent(resultCallback, failureCallback);
The intentShim.getIntent function maps to Android's activity method getIntent, https://developer.android.com/reference/android/app/Activity.html#getIntent() to return the intent that started this activity.
window.plugins.intentShim.getIntent(
function(intent)
{
console.log('Action' + JSON.stringify(intent.action));
var intentExtras = intent.extras;
if (intentExtras == null)
intentExtras = "No extras in intent";
console.log('Launch Intent Extras: ' + JSON.stringify(intentExtras));
},
function()
{
console.log('Error getting launch intent');
});
Starts a new activity and return the result to the application
window.plugins.intentShim.startActivityForResult(params, resultCallback, failureCallback);
The intentShim.startActivityForResult function maps to Android's activity method startActivityForResult, https://developer.android.com/reference/android/app/Activity.html#startActivityForResult(android.content.Intent, int) to launch a new activity and the resulting data is returned via the resultCallback.
Some common actions are defined as constants in the plugin, see below.
Pick an Android contact
window.plugins.intentShim.startActivityForResult(
{
action: window.plugins.intentShim.ACTION_PICK,
url: "content://com.android.contacts/contacts",
requestCode: 1
},
function(intent)
{
if (intent.extras.requestCode == 1)
{
console.log('Picked contact: ' + intent.data);
}
},
function()
{
console.log("StartActivityForResult failure");
});
Assuming this application was started with intentShim.startActivityForResult, send a result back
window.plugins.intentShim.sendResult(args, callback);
The intentShim.sendResult function returns an Activity.RESULT_OK Intent to the activity that started this application, along with any extras that you want to send along (as args.extras object), and a callback function. It then calls Android Activity's finish() method, https://developer.android.com/reference/android/app/Activity.html#finish().
Both args and callback arguments have to be provided. If you do not need the functionality, send an empty object and an empty function
window.plugins.intentShim.sendResult({}, function() {});
window.plugins.intentShim.sendResult(
{
extras: {
'Test Intent': 'Successfully sent',
'Test Intent int': 42,
'Test Intent bool': true,
'Test Intent double': parseFloat("142.12")
}
},
function() {
}
);
The following constants are defined in the plugin for use in JavaScript
- window.plugins.intentShim.ACTION_SEND
- window.plugins.intentShim.ACTION_VIEW
- window.plugins.intentShim.EXTRA_TEXT
- window.plugins.intentShim.EXTRA_SUBJECT
- window.plugins.intentShim.EXTRA_STREAM
- window.plugins.intentShim.EXTRA_EMAIL
- window.plugins.intentShim.ACTION_CALL
- window.plugins.intentShim.ACTION_SENDTO
- window.plugins.intentShim.ACTION_GET_CONTENT
- window.plugins.intentShim.ACTION_PICK
Tested with Cordova version 6.5.0 and Cordova Android version 6.2.1