This plugin provides Host Card Emulation (HCE) for Apache Cordova. Host-based card emulation allows a Cordova application emulate a NFC Smart Card (without using the secure element) and talk directly to the NFC reader.
This plugin provides a low-level access. The plugin receives commands as Uint8Arrays and expects responses to be Uint8Arrays. As a developer, you must implement higher level protocols based on your applications needs.
Host Card Emulation requires NFC.
- Android (API Level 19 KitKat)
The AID for your application must be passed as a variable when installing the plugin.
cordova plugin add cordova-plugin-hce --variable AID_FILTER=F222222222
The hce object provides functions that allow your application to emulate a smart card.
Register to receive APDU commands from the remote device.
hce.registerCommandCallback(onCommand);
- success: Success callback function that is invoked when an APDU command arrives.
- failure: Error callback function, invoked when error occurs. [optional]
Function registerCommandCallback allows your JavaScript code to handle APDU responses from the NFC reader. Commands will be sent as Uint8Array to the success callback. The success callback is long lived and may be called many times.
Responses are sent back using hce.sendResponse. Android recommends "...response APDUs must be sent as quickly as possible, given the fact that the user is likely holding his device over an NFC reader when this method is called." For more info see [HostApduService.processCommandApdu](http://developer.android.com/reference/android/nfc/cardemulation/HostApduService.html#processCommandApdu(byte[], android.os.Bundle)).
hce.registerCommandCallback(onCommand);
var onCommand = function(command) {
var commandAsBytes = new Uint8Array(command);
var commandAsString = hce.util.byteArrayToHexString(commandAsBytes);
// do something with the command
// send the response
hce.sendReponse(commandResponse);
}
Sends a response APDU back to the remote device.
hce.sendResponse(responseApdu, success);
- responseApdu: Response for NFC reader. Should be a Uint8Array.
- success: Success callback function that is invoked when an APDU command arrives.
- failure: Error callback function, invoked when error occurs. [optional]
Function sendResponse is intended to be called from within the success handler of hce.registerCommandCallback. Response commands should be sent a Uint8Array.
See HostApduService.sendResponseApdu.
Register to receive callback when host service is deactivated.
hce.registerDeactivatedCallback(onDeactivated);
- success: Success callback function that is invoked when the service is deactivated.
- failure: Error callback function, invoked when error occurs. [optional]
Function registerDeactivatedCallback allows the plugin to be notified when the host service is deactivated. A reason code is passed to the success callback.
See HostApduService.onDeactivated.
hce.registerDeactivatedCallback(onDeactivated);
var onDeactivated = function(reason) {
console.log("Deactivated. Reason code = " + reason);
}
The hce.util object provides utility function for APDU operations.
- hexStringToByteArray - convert hex string to ArrayBuffer
- byteArrayToHexString - convert ArrayBuffer to hex string
- stringToBytes - convert ascii string into ArrayBuffer
- concatenateBuffers - concatenate two ArrayBuffer together, returning a new ArrayBuffer
This plugin is a wrapper around the Android HCE functionality. Reference the Android HCE documentation for more info.
See the HCE Demo application for one possible use of this plugin. The HCE demo application duplicates Android's card emulation example in Cordova and is intended to work with the Android card reader example.
Apache 2.0