phonegap-nfc
Advanced tools
Near Field Communication (NFC) Plugin. Read and write NDEF messages to NFC tags and share NDEF messages with peers.
The NFC plugin allows you to read and write NFC tags. You can also beam to, and receive from, other NFC enabled devices.
Use to
This plugin uses NDEF (NFC Data Exchange Format) for maximum compatibilty between NFC devices, tag types, and operating systems.
$ cordova plugin add phonegap-nfc
$ phonegap plugin add phonegap-nfc
Edit config.xml to install the plugin for PhoneGap Build.
<gap:plugin name="phonegap-nfc" source="npm" />
Windows Phone 8.1 should use the windows platform. The Silverlight based Windows Phone 8 code is no longer being maintained.
BlackBerry 7 support is only available for Cordova 2.x. For applications targeting BlackBerry 7, you may need to use an older version of phonegap-nfc.
See Getting Started and Getting Started BlackBerry 10for more details.
Reading NFC NDEF tags is supported on iPhone 7 and iPhone 7 Plus running iOS 11. To enable your app to detect NFC tags, the plugin adds the Near Field Communication Tag Reading capability in your Xcode project. You must build your application with XCode 9. See the Apple Documentation for more info.
Use nfc.addNdefListener to read NDEF NFC tags with iOS. Unfortunately, iOS also requires you to begin a session before scanning NFC tag. The JavaScript API contains two new iOS specific functions nfc.beginSession and nfc.invalidateSession.
You must call nfc.beginSession before every scan.
The initial iOS version plugin does not support scanning multiple tags (invalidateAfterFirstRead:FALSE) or setting the alertMessage. If you have use cases or suggestions on the best way to support multi-read or alert messages, open a ticket for discussion.
The nfc object provides access to the device's NFC sensor.
Registers an event listener for any NDEF tag.
nfc.addNdefListener(callback, [onSuccess], [onFailure]);
Function nfc.addNdefListener registers the callback for ndef events.
A ndef event is fired when a NDEF tag is read.
For BlackBerry 10, you must configure the type of tags your application will read with an invoke-target in config.xml.
On Android registered mimeTypeListeners takes precedence over this more generic NDEF listener.
On iOS you must call beingSession before scanning a tag.
Removes the previously registered event listener for NDEF tags added via nfc.addNdefListener.
nfc.removeNdefListener(callback, [onSuccess], [onFailure]);
Registers an event listener for tags matching any tag type.
nfc.addTagDiscoveredListener(callback, [onSuccess], [onFailure]);
Function nfc.addTagDiscoveredListener registers the callback for tag events.
This event occurs when any tag is detected by the phone.
Note that Windows Phones need the newere NXP PN427 chipset to read non-NDEF tags. That tag will be read, but no tag meta-data is available.
Removes the previously registered event listener added via nfc.addTagDiscoveredListener.
nfc.removeTagDiscoveredListener(callback, [onSuccess], [onFailure]);
Registers an event listener for NDEF tags matching a specified MIME type.
nfc.addMimeTypeListener(mimeType, callback, [onSuccess], [onFailure]);
Function nfc.addMimeTypeListener registers the callback for ndef-mime events.
A ndef-mime event occurs when a Ndef.TNF_MIME_MEDIA tag is read and matches the specified MIME type.
This function can be called multiple times to register different MIME types. You should use the same handler for all MIME messages.
nfc.addMimeTypeListener("text/json", *onNfc*, success, failure);
nfc.addMimeTypeListener("text/demo", *onNfc*, success, failure);
On Android, MIME types for filtering should always be lower case. (See IntentFilter.addDataType())
Removes the previously registered event listener added via nfc.addMimeTypeListener.
nfc.removeMimeTypeListener(mimeType, callback, [onSuccess], [onFailure]);
Registers an event listener for formatable NDEF tags.
nfc.addNdefFormatableListener(callback, [onSuccess], [onFailure]);
Function nfc.addNdefFormatableListener registers the callback for ndef-formatable events.
A ndef-formatable event occurs when a tag is read that can be NDEF formatted. This is not fired for tags that are already formatted as NDEF. The ndef-formatable event will not contain an NdefMessage.
Writes an NDEF Message to a NFC tag.
A NDEF Message is an array of one or more NDEF Records
var message = [
ndef.textRecord("hello, world"),
ndef.uriRecord("http://github.com/chariotsolutions/phonegap-nfc")
];
nfc.write(message, [onSuccess], [onFailure]);
Function nfc.write writes an NdefMessage to a NFC tag.
On Android this method must be called from within an NDEF Event Handler. On Windows this method may be called from within the NDEF Event Handler.
On Windows Phone 8.1 this method should be called outside the NDEF Event Handler, otherwise Windows tries to read the tag contents as you are writing to the tag.
Makes a NFC tag read only. Warning this is permanent.
nfc.makeReadOnly([onSuccess], [onFailure]);
Function nfc.makeReadOnly make a NFC tag read only. Warning this is permanent and can not be undone.
On Android this method must be called from within an NDEF Event Handler.
Example usage
onNfc: function(nfcEvent) {
var record = [
ndef.textRecord("hello, world")
];
var failure = function(reason) {
alert("ERROR: " + reason);
};
var lockSuccess = function() {
alert("Tag is now read only.");
};
var lock = function() {
nfc.makeReadOnly(lockSuccess, failure);
};
nfc.write(record, lock, failure);
},
Shares an NDEF Message via peer-to-peer.
A NDEF Message is an array of one or more NDEF Records
var message = [
ndef.textRecord("hello, world")
];
nfc.share(message, [onSuccess], [onFailure]);
Function nfc.share writes an NdefMessage via peer-to-peer. This should appear as an NFC tag to another device.
Android - shares message until unshare is called
Blackberry 10 - shares the message one time or until unshare is called
Windows Phone 8 - must be called from within a NFC event handler like nfc.write
Stop sharing NDEF data via peer-to-peer.
nfc.unshare([onSuccess], [onFailure]);
Function nfc.unshare stops sharing data via peer-to-peer.
Erase a NDEF tag
nfc.erase([onSuccess], [onFailure]);
Function nfc.erase erases a tag by writing an empty message. Will format unformatted tags before writing.
This method must be called from within an NDEF Event Handler.
Send a file to another device via NFC handover.
var uri = "content://media/external/audio/media/175";
nfc.handover(uri, [onSuccess], [onFailure]);
var uris = [
"content://media/external/audio/media/175",
"content://media/external/audio/media/176",
"content://media/external/audio/media/348"
];
nfc.handover(uris, [onSuccess], [onFailure]);
Function nfc.handover shares files to a NFC peer using handover. Files are sent by specifying a file:// or context:// URI or a list of URIs. The file transfer is initiated with NFC but the transfer is completed with over Bluetooth or WiFi which is handled by a NFC handover request. The Android code is responsible for building the handover NFC Message.
This is Android only, but it should be possible to add implementations for other platforms.
Stop sharing NDEF data via NFC handover.
nfc.stopHandover([onSuccess], [onFailure]);
Function nfc.stopHandover stops sharing data via peer-to-peer.
Show the NFC settings on the device.
nfc.showSettings(success, failure);
Function showSettings opens the NFC settings for the operating system.
nfc.showSettings();
Check if NFC is available and enabled on this device.
nfc.enabled(onSuccess, onFailure);
Function nfc.enabled explicitly checks to see if the phone has NFC and if NFC is enabled. If
everything is OK, the success callback is called. If there is a problem, the failure callback
will be called with a reason code.
The reason will be NO_NFC if the device doesn't support NFC and NFC_DISABLED if the user has disabled NFC.
Note: that on Android the NFC status is checked before every API call NO_NFC or NFC_DISABLED can be returned in any failure function.
Windows will return NO_NFC_OR_NFC_DISABLED when NFC is not present or disabled. If the user disabled NFC after the application started, Windows may return NFC_DISABLED. Windows checks the NFC status before most API calls, but there are some cases when the NFC state can not be determined.
iOS requires you to begin a session before scanning a NFC tag.
nfc.beginSession(success, failure);
Function beginSession starts the NFCNDEFReaderSession allowing iOS to scan NFC tags.
nfc.beginSession();
Invalidate the NFC session.
nfc.invalidateSession(success, failure);
Function invalidateSession stops the NFCNDEFReaderSession returning control to your app.
nfc.invalidateSession();
The tag technology functions provide access to I/O operations on a tag. Connect to a tag, send commands with tranceive, close the tag. See the Android TagTechnology and implementations like IsoDep and NfcV for more details. These new APIs are promise based rather than using callbacks.
const DESFIRE_SELECT_PICC = '00 A4 04 00 07 D2 76 00 00 85 01 00';
const DESFIRE_SELECT_AID = '90 5A 00 00 03 AA AA AA 00'
async function handleDesfire(nfcEvent) {
const tagId = nfc.bytesToHexString(nfcEvent.tag.id);
console.log('Processing', tagId);
try {
await nfc.connect('android.nfc.tech.IsoDep', 500);
console.log('connected to', tagId);
let response = await nfc.transceive(DESFIRE_SELECT_PICC);
ensureResponseIs('9000', response);
response = await nfc.transceive(DESFIRE_SELECT_AID);
ensureResponseIs('9100', response);
// 91a0 means the requested application not found
alert('Selected application AA AA AA');
// more transcieve commands go here
} catch (error) {
alert(error);
} finally {
await nfc.close();
console.log('closed');
}
}
function ensureResponseIs(expectedResponse, buffer) {
const responseString = util.arrayBufferToHexString(buffer);
if (expectedResponse !== responseString) {
const error = 'Expecting ' + expectedResponse + ' but received ' + responseString;
throw error;
}
}
function onDeviceReady() {
nfc.addTagDiscoveredListener(handleDesfire);
}
document.addEventListener('deviceready', onDeviceReady, false);
Connect to the tag and enable I/O operations to the tag from this TagTechnology object.
nfc.connect(tech);
nfc.connect(tech, timeout);
Function connect enables I/O operations to the tag from this TagTechnology object. nfc.connect should be called after receiving a nfcEvent from the addTagDiscoveredListener. Only one TagTechnology object can be connected to a Tag at a time.
See Android's TagTechnology.connect() for more info.
nfc.addTagDiscoveredListener(function(nfcEvent) {
nfc.connect('android.nfc.tech.IsoDep', 500).then(
() => console.log('connected to', nfc.bytesToHexString(nfcEvent.tag.id)),
(error) => console.log('connection failed', error)
);
})
Send raw command to the tag and receive the response.
nfc.transceive(data);
Function transceive sends raw commands to the tag and receives the response. nfc.connect must be called before calling transceive. Data passed to transceive can be a hex string representation of bytes or an ArrayBuffer. The response is returned as an ArrayBuffer in the promise.
See Android's documentation IsoDep.transceive(), NfcV.transceive(), MifareUltralight.transceive() for more info.
// Promise style
nfc.transceive('90 5A 00 00 03 AA AA AA 00').then(
response => console.log(util.arrayBufferToString(response)),
error => console.log('Error selecting DESFire application')
)
// async await
const response = await nfc.transceive('90 5A 00 00 03 AA AA AA 00');
console.log('response =',util.arrayBufferToString(response));
Close TagTechnology connection.
nfc.close();
Function close disabled I/O operations to the tag from this TagTechnology object, and releases resources.
See Android's TagTechnology.close() for more info.
nfc.transceive().then(
() => console.log('connection closed'),
(error) => console.log('error closing connection', error);
)
The
ndefobject provides NDEF constants, functions for creating NdefRecords, and functions for converting data. See android.nfc.NdefRecord for documentation about constants
Represents an NDEF (NFC Data Exchange Format) data message that contains one or more NdefRecords. This plugin uses an array of NdefRecords to represent an NdefMessage.
Represents a logical (unchunked) NDEF (NFC Data Exchange Format) record.
The ndef object has a function for creating NdefRecords
var type = "text/pg",
id = [],
payload = nfc.stringToBytes("Hello World"),
record = ndef.record(ndef.TNF_MIME_MEDIA, type, id, payload);
There are also helper functions for some types of records
Create a URI record
var record = ndef.uriRecord("http://chariotsolutions.com");
Create a plain text record
var record = ndef.textRecord("Plain text message");
Create a mime type record
var mimeType = "text/pg",
payload = "Hello Phongap",
record = ndef.mimeMediaRecord(mimeType, nfc.stringToBytes(payload));
Create an Empty record
var record = ndef.emptyRecord();
Create an Android Application Record (AAR)
var record = ndef.androidApplicationRecord('com.example');
See ndef.record, ndef.textRecord, ndef.mimeMediaRecord, and ndef.uriRecord.
The Ndef object has functions to convert some data types to and from byte arrays.
See the phonegap-nfc.js source for more documentation.
Events are fired when NFC tags are read. Listeners are added by registering callback functions with the nfc object. For example nfc.addNdefListener(myNfcListener, win, fail);
The tag contents are platform dependent.
id and techTypes may be included when scanning a tag on Android. serialNumber may be included on BlackBerry 7.
id and serialNumber are different names for the same value. id is typically displayed as a hex string nfc.bytesToHexString(tag.id).
Windows, Windows Phone 8, and BlackBerry 10 read the NDEF information from a tag, but do not have access to the tag id or other meta data like capacity, read-only status or tag technologies.
Assuming the following NDEF message is written to a tag, it will produce the following events when read.
var ndefMessage = [
ndef.createMimeRecord('text/pg', 'Hello PhoneGap')
];
{
type: 'ndef',
tag: {
"isWritable": true,
"id": [4, 96, 117, 74, -17, 34, -128],
"techTypes": ["android.nfc.tech.IsoDep", "android.nfc.tech.NfcA", "android.nfc.tech.Ndef"],
"type": "NFC Forum Type 4",
"canMakeReadOnly": false,
"maxSize": 2046,
"ndefMessage": [{
"id": [],
"type": [116, 101, 120, 116, 47, 112, 103],
"payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112],
"tnf": 2
}]
}
}
{
type: 'ndef',
tag: {
"tagType": "4",
"isLocked": false,
"isLockable": false,
"freeSpaceSize": "2022",
"serialNumberLength": "7",
"serialNumber": [4, 96, 117, 74, -17, 34, -128],
"name": "Desfire EV1 2K",
"ndefMessage": [{
"tnf": 2,
"type": [116, 101, 120, 116, 47, 112, 103],
"id": [],
"payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112]
}]
}
}
{
type: 'ndef',
tag: {
"ndefMessage": [{
"tnf": 2,
"type": [116, 101, 120, 116, 47, 112, 103],
"id": [],
"payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112]
}]
}
}
The raw contents of the scanned tags are written to the log before the event is fired. Use adb logcat on Android and Event Log (hold alt + lglg) on BlackBerry.
You can also log the tag contents in your event handlers. console.log(JSON.stringify(nfcEvent.tag)) Note that you want to stringify the tag not the event to avoid a circular reference.
Only Android and BlackBerry 7 can read data from non-NDEF NFC tags. Newer Windows Phones with NXP PN427 chipset can read non-NDEF tags, but can not get any tag meta data.
BlackBerry 7, BlackBerry 10 and many newer Android phones will not read Mifare Classic tags. Mifare Ultralight tags will work since they are NFC Forum Type 2 tags. Newer Windows 8.1 phones (Lumia 640) can read Mifare Classic tags.
Windows Phone 8, BlackBerry 10, and Windows read the NDEF information from a tag, but do not have access to the tag id or other meta data like capacity, read-only status or tag technologies.
Multiple listeners can be registered in JavaScript. e.g. addNdefListener, addTagDiscoveredListener, addMimeTypeListener.
On Android, only the most specific event will fire. If a Mime Media Tag is scanned, only the addMimeTypeListener callback is called and not the callback defined in addNdefListener. You can use the same event handler for multiple listeners.
For Windows, this plugin mimics the Android behavior. If an ndef event is fired, a tag event will not be fired. You should receive one event per tag.
On BlackBerry 7, all the events fire if a Mime Media Tag is scanned.
On Android, addTagDiscoveredListener scans non-NDEF tags and NDEF tags. The tag event does NOT contain an ndefMessage even if there are NDEF messages on the tag. Use addNdefListener or addMimeTypeListener to get the NDEF information.
Windows can scan non-NDEF (unformatted) tags using addTagDiscoveredListener. The tag event will not include any data.
On BlackBerry 7, addTagDiscoveredListener does NOT scan non-NDEF tags. Webworks returns the ndefMessage in the event.
{
type: 'tag',
tag: {
"id": [-81, 105, -4, 64],
"techTypes": ["android.nfc.tech.MifareClassic", "android.nfc.tech.NfcA", "android.nfc.tech.NdefFormatable"]
}
}
{
type: 'tag',
tag: {
"id": [4, 96, 117, 74, -17, 34, -128],
"techTypes": ["android.nfc.tech.IsoDep", "android.nfc.tech.NfcA", "android.nfc.tech.Ndef"]
}
}
{
type: 'tag',
tag: {
}
}
This plugin uses the BlackBerry Invocation Framework to read NFC tags on BlackBerry 10. This means that you need to register an invoke target in the config.xml.
If your project supports multiple platforms, copy www/config.xml to merges/config.xml and add a rim:invoke-target tag. The invoke-target determines which tags your app will scan when it is running. If your application is not running, BlackBerry will launch it when a matching tag is scanned.
This sample configuration attempts to open any NDEF tag.
<rim:invoke-target id="your.unique.id.here">
<type>APPLICATION</type>
<filter>
<action>bb.action.OPEN</action>
<mime-type>application/vnd.rim.nfc.ndef</mime-type>
<!-- any TNF Empty(0), Well Known(1), MIME Media(2), Absolute URI(3), External(4) -->
<property var="uris" value="ndef://0,ndef://1,ndef://2,ndef://3,ndef://4" />
</filter>
</rim:invoke-target>
You can configure you application to handle only certain tags.
For example to scan only MIME Media tags of type "text/pg" use
<rim:invoke-target id="your.unique.id.here">
<type>APPLICATION</type>
<filter>
<action>bb.action.OPEN</action>
<mime-type>application/vnd.rim.nfc.ndef</mime-type>
<!-- TNF MIME Media(2) with type "text/pg" -->
<property var="uris" value="ndef://2/text/pg" />
</filter>
</rim:invoke-target>
Or to scan only Plain Text tags use
<rim:invoke-target id="your.unique.id.here">
<type>APPLICATION</type>
<filter>
<action>bb.action.OPEN</action>
<mime-type>application/vnd.rim.nfc.ndef</mime-type>
<!-- TNF Well Known(1), RTD T -->
<property var="uris" value="ndef://1/T" />
</filter>
</rim:invoke-target>
See the BlackBerry documentation for more info.
On Android, intents can be used to launch your application when a NFC tag is read. This is optional and configured in AndroidManifest.xml.
<intent-filter>
<action android:name="android.nfc.action.NDEF_DISCOVERED" />
<data android:mimeType="text/pg" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
Note: data android:mimeType="text/pg" should match the data type you specified in JavaScript
We have found it necessary to add android:noHistory="true" to the activity element so that scanning a tag launches the application after the user has pressed the home button.
See the Android documentation for more information about filtering for NFC intents.
Tests require the Cordova Plugin Test Framework
Create a new project
git clone https://github.com/chariotsolutions/phonegap-nfc
cordova create nfc-test com.example.nfc.test NfcTest
cd nfc-test
cordova platform add android
cordova plugin add ../phonegap-nfc
cordova plugin add ../phonegap-nfc/tests
cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-test-framework.git
Change the start page in config.xml
<content src="cdvtests/index.html" />
Run the app on your phone
cordova run
For Host Card Emulation (HCE), try the Cordova HCE Plugin.
Need more info? Check out my book
Beginning NFC: Near Field Communication with Arduino, Android, and PhoneGap
The MIT License
Copyright (c) 2011-2017 Chariot Solutions
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
FAQs
Near Field Communication (NFC) Plugin. Read and write NDEF messages to NFC tags and share NDEF messages with peers.
The npm package phonegap-nfc receives a total of 460 weekly downloads. As such, phonegap-nfc popularity was classified as not popular.
We found that phonegap-nfc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.