Nomnom Pumpernickle Muffins
    Wondering what’s next for npm?Check out our public roadmap! »

    @fintom/cordova-nfc-tag

    1.0.0 • Public • Published

    Cordova NFC Tag Plugin

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

    Supported Platforms

    Contents

    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

    Beginning NFC

    Install

    npm i @fintom/cordova-nfc-tag

    DownloadsWeekly Downloads

    0

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    79.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar
    • avatar