@fintom/cordova-nfc v1.0.0

Cordova NFC Tag Plugin

The NFC plugin allows you to to send raw commands (ISO 15693) to NFC tags.

Supported Platforms

• Android
• iOS 13

Contents

• Installing
• NFC
• Testing
• Book

Installing

Cordova

$ cordova plugin add cordova-nfc-tag

iOS Notes

With iOS 13, Apple opened its NFC API and allowed communication with ISO15693 tags.

Use nfc.connect to begin a NFC communication session in your iOS app. you may then use the nfc.transceive method to exchange, and then close the session with nfc.close

NFC Tag Technology Functions

The tag technology functions provide access to I/O operations on a tag. Connect to a tag, send commands with transceive, 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.

ISO-DEP (ISO 14443-4) Example

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);

nfc.connect

Connect to the tag and enable I/O operations to the tag from this TagTechnology object.

nfc.connect(tech);

nfc.connect(tech, timeout);

Description

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 or the readerMode callback. Only one TagTechnology object can be connected to a Tag at a time.

See Android's TagTechnology.connect() for more info.

Parameters

• tech: The tag technology e.g. android.nfc.tech.IsoDep
• timeout: The transceive(byte[]) timeout in milliseconds optional

Returns

• Promise when the connection is successful, optionally with a maxTransceiveLength attribute in case the tag technology supports it

Quick Example

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)
    );
})

Supported Platforms

• Android
• iOS 13+

nfc.transceive

Send raw command to the tag and receive the response.

nfc.transceive(data);

Description

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.

Parameters

• data: a string of hex data or an ArrayBuffer

Returns

• Promise with the response data as an ArrayBuffer

Quick Example

// Promise style
nfc.transceive('90 5A 00 00 03 AA AA AA 00').then(
    response => console.log(util.arrayBufferToHexString(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.arrayBufferToHexString(response));

Supported Platforms

• Android
• iOS 13+

nfc.close

Close TagTechnology connection.

nfc.close();

Description

Function close disabled I/O operations to the tag from this TagTechnology object, and releases resources.

See Android's TagTechnology.close() for more info.

Parameters

• none

Returns

• Promise when the connection is successfully closed

Quick Example

nfc.transceive().then(
    () => console.log('connection closed'),
    (error) => console.log('error closing connection', error);
)

Supported Platforms

• Android
• iOS 13+

Launching your Android Application when Scanning a Tag

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.

Testing

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 https://github.com/apache/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

Book

Need more info? Check out my book Beginning NFC: Near Field Communication with Arduino, Android, and PhoneGap