Cordova HCE Plugin
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.
Supported Platforms
- Android (API Level 19 KitKat)
Installing
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
HCE
The hce object provides functions that allow your application to emulate a smart card.
Methods
hce.registerCommandCallback
Register to receive APDU commands from the remote device.
hce.registerCommandCallback(onCommand);
Parameters
- success: Success callback function that is invoked when an APDU command arrives.
- failure: Error callback function, invoked when error occurs. [optional]
Description
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.
Quick Example
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);
}
hce.sendResponse
Sends a response APDU back to the remote device.
hce.sendResponse(responseApdu, success);
Parameters
- 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]
Description
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.
hce.registerDeactivatedCallback
Register to receive callback when host service is deactivated.
hce.registerDeactivatedCallback(onDeactivated);
Parameters
- success: Success callback function that is invoked when the service is deactivated.
- failure: Error callback function, invoked when error occurs. [optional]
Description
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.
Quick Example
hce.registerDeactivatedCallback(onDeactivated);
var onDeactivated = function(reason) {
console.log("Deactivated. Reason code = " + reason);
}
HCE Util
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
Android HCE documentation
This plugin is a wrapper around the Android HCE functionality. Reference the Android HCE documentation for more info.
HCE Demo App
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.
License
Apache 2.0