PhoneGap NFC Plugin
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-nfcEdit config.xml to install the plugin for PhoneGap Build.
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 newer) since iOS 11. iOS 13 added support for writing NDEF messages to NFC tags. iOS 13 also adds the ability to get the UID from some NFC tags. On iOS, the user must start a NFC session to scan for a tag. This is different from Android which can constantly scan for NFC tags. The nfc.scanNdef and nfc.scanTag functions start a NFC scanning session. The NFC tag is returned to the caller via a Promise. If your existing code uses the deprecated nfc.beginSession, update it to use nfc.scanNdef.
The scanNdef function uses NFCNDEFReaderSession to detect NFC Data Exchange Format (NDEF) tags. scanTag uses the newer NFCTagReaderSession available in iOS 13 to detect ISO15693, FeliCa, and MIFARE tags. The scanTag function will include the tag UID and tag type for some NFC tags along with the NDEF messages. scanTag can also read some RFID tags without NDEF messsages. scanTag will not scan some NDEF tags including Topaz and Mifare Classic.
You must call nfc.scanNdef and nfc.scanTag before every scan.
Writing NFC tags on iOS uses the same nfc.write function as other platforms. Although it's the same function, the behavior is different on iOS. Calling nfc.write on an iOS device will start a new scanning session and write data to the scanned tag.
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]);Removing listeners is not recommended. Instead, consider that your callback can ignore messages you no longer need.
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]);Removing listeners is not recommended. Instead, consider that your callback can ignore messages you no longer need.
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]);Removing listeners is not recommended. Instead, consider that your callback can ignore messages you no longer need.
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 iOS this method can be called outside the NDEF Event Handler, it will start a new scanning session. Optionally you can reuse the read session to write data. See example below.
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.
On Android, write must be called inside an event handler
function onNfc(nfcEvent) {
console.log(nfcEvent.tag);
var message = [
ndef.textRecord(new String(new Date()))
];
nfc.write(
message,
success => console.log('wrote data to tag'),
error => console.log(error)
);
nfc.addNdefListener(onNfc);Calling nfc.write on iOS will create a new session and write data when the user taps a NF
No open issues yet, or sync has not completed.