Announcing the Capacitor NFC Plugin

Today we are happy to introduce the brand new Capacitor NFC plugin from Capawesome, sponsored by NFC21. This plugin enables interaction with Near Field Communication (NFC) tags and provides cross-platform support for Android, iOS, and Web. The project is available as Sponsorware on GitHub.

Let's take a quick look at the Capacitor NFC API and how you can read and write on passive NFC tags and stickers. For this we will use the NTAG 215 from this NFC Starter Kit.

Installation

See Getting started with Insiders and follow the instructions to install the plugin.

After that, follow the platform-specific instructions in the sections Android and iOS.

Android

The NFC API requires the following permissions be added to your AndroidManifest.xml before the application tag:

<uses-permission android:name="android.permission.NFC" />
<uses-sdk android:minSdkVersion="10"/>

iOS

Make sure that the Near Field Communication Tag Reading capabilities have been enabled in your application in Xcode. See Add a capability to a target for more information.

Finally, add the NFCReaderUsageDescription key to the ios/App/App/Info.plist file, which tells the user why the app needs to use NFC:

<key>NFCReaderUsageDescription</key>
<string>The app enables the reading and writing of various NFC tags.</string>

Usage

Now let's finally start and see the plugin in action.

Read NFC tags

Reading NFC tags is quite simple:

import { Nfc } from "@capawesome-team/capacitor-nfc";

const read = async () => {
  return new Promise((resolve) => {
    Nfc.addListener("nfcTagScanned", async (event) => {
      await Nfc.stopScanSession();
      resolve(event.nfcTag);
    });

    Nfc.startScanSession();
  });
};

First you have to add the nfcTagScanned listener. This listener is called when an NFC tag is scanned as well as when an NFC tag opens your app. As soon as the listener is active, you can start a new scan session with Nfc.startScanSession(...). During this session the operating system is looking for NFC tags. Once you are done, end the session with Nfc.stopScanSession(...).

Write NFC tags

An NFC tag can contain different types of data in different formats such as NDEF. NDEF means NFC Data Exchange Format and defines in which format data is stored on NFC tags and in which way it can be read.

Here we create a simple NDEF text record using NfcUtils, a utility class with various helper functions:

import { NfcUtils } from "@capawesome-team/capacitor-nfc";

const createNdefTextRecord = () => {
  const utils = new NfcUtils();
  const { record } = utils.createNdefTextRecord({
    text: "Capacitor NFC Plugin",
  });
  return record;
};

This record can now be written to an NFC tag. A NFC tag may be written to at the moment it is scanned. That means we have to add the nfcTagScanned listener again.

import { Nfc } from "@capawesome-team/capacitor-nfc";

const write = async () => {
  return new Promise((resolve) => {
    const record = createNdefTextRecord();

    Nfc.addListener("nfcTagScanned", async (event) => {
      await Nfc.write({ message: { records: [record] } });
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};

Now we can call Nfc.write(...) and write the record to the NFC tag while the tag is being scanned.

Make NFC tags read-only

It is possible to make NFC tags permanently read-only using the makeReadOnly method:

import { Nfc } from "@capawesome-team/capacitor-nfc";

const makeReadOnly = async () => {
  return new Promise((resolve) => {
    Nfc.addListener("nfcTagScanned", async (event) => {
      await Nfc.makeReadOnly();
      await Nfc.stopScanSession();
      resolve();
    });

    Nfc.startScanSession();
  });
};

Warning

This is a one-way operation and cannot be undone. Once an NFC tag has been made read-only, it can no longer be written to.

Send custom commands to NFC tags

And finally, we can send custom commands to the NFC tag. Which NFC tag supports which commands can be found in the respective specification of the tag. The specification for NTAG 215 can be found here.

Note

The codes in the specifications are often in hex format, but the plugin needs them as byte array. The convertHexToBytes(...) method can help you with this.

In the following example we read the signature of the tag:

import { Nfc } from "@capawesome-team/capacitor-nfc";

const readSignature = async () => {
  return new Promise((resolve) => {
    Nfc.addListener("nfcTagScanned", async (event) => {
      const { response } = await Nfc.transceive({
        techType: NfcTagTechType.NfcA,
        data: [60, 0],
      });
      await Nfc.stopScanSession();
      resolve(response);
    });

    Nfc.startScanSession();
  });
};

For this, we send the command ([60, 0]) to the tag using the Nfc.transceive(...) method and receive the signature as a byte array.

Closing Thoughts

Be sure to check out our API Reference to see what else you can do with this plugin. Also feel free to take a look at our Demo App which shows this plugin in action.