GitHub - rbaumi/capacitor-nfc: ⚡️ Capacitor plugin for reading and writing NFC tags.

NFC

@capawesome-team/capacitor-nfc

Capacitor plugin for reading and writing NFC tags.

Maintainers

Maintainer	GitHub	Social
Robin Genz	robingenz	@robin_genz

Sponsorware

This project is available as Sponsorware.

Sponsorware is a release strategy for open-source software that enables developers to be compensated for their open-source work with fewer downsides than traditional open-source funding models. (Source)

This means...

The source code will be published as soon as our GitHub Sponsors goal is reached.
Any GitHub sponsor with a sponsorware tier gets immediate access to our sponsors-only repository and can start using the project right away.

Terms

This project is licensed under the terms of the MIT license.
However, we kindly ask you to respect our fair use policy:

Please don't distribute the source code of the sponsors-only repository. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy.
If you cancel your subscription, you're automatically removed as a collaborator and will miss out on all future updates. However, you may use the latest version that's available to you as long as you like.

Demo

A working example can be found here: capawesome-team/capacitor-nfc-demo

Android	iOS

Roadmap

This plugin is still under development. This is our approximate roadmap:

Q4 2022
- Android Reader Mode

⚠️ Disclaimer: This roadmap does not represent a commitment, guarantee, obligation or promise to deliver any product or feature, or to deliver any product and feature by any particular date, and is intended to outline the general development plans. You should not rely on this roadmap to make any sponsorship decision.

FAQ

Which platforms are supported?
This plugin supports Android 5+, iOS 13+ and Web (see Browser compatibility). But not all platforms and devices support all technologies. You can read more about this in the plugin documentation.
Which Capacitor versions are supported?
There is a version for Capacitor 3 and Capacitor 4. However, new updates are only ever provided for the latest Capacitor major version (currently Capacitor 4).
What do I do when I have a feature request?
This always depends on your device and the specific tag. The easiest way to find out is to download our demo app and give it a try.
What do I do when I have a feature request?
Please submit your feature request here. We will then review it and possibly put it on our roadmap.
What do I do when I have found a bug?
Bug reports have top priority. Please submit your bug report here. We will take a look at it as soon as possible.

Installation

As long as the project is available as Sponsorware, the project will be distributed via GitHub packages.

Log in to GitHub package registry (GitHub Docs):

$ npm login --scope=@capawesome-team --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

In the same directory as your package.json file, create or edit an .npmrc file to include the following line (GitHub Docs):
```
@capawesome-team:registry=https://npm.pkg.github.com
```
Install the package with Capacitor 3:
```
npm install @capawesome-team/[email protected]
npx cap sync
```
Install the package with Capacitor 4:
```
npm install @capawesome-team/capacitor-nfc
npx cap sync
```
🆘 If you have any problems please contact us by mail or create a GitHub discussion in this repository.
⚠️ Attention: Be careful not to disclose your npm auth token! If you have any questions (CI configuration etc.) please let us know.

Android

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

<!-- To get access to the NFC hardware. -->
<uses-permission android:name="android.permission.NFC" />
<!-- The minimum SDK version that your application can support. -->
<uses-sdk android:minSdkVersion="10"/>
<!-- (Optional) This will ensure that your app appears in Google Play only for devices with NFC hardware. -->
<uses-feature android:name="android.hardware.nfc" android:required="true" />

If you want to launch your app through an NFC tag, please take a look at the Android documentation. There you will find which changes you have to apply to your AndroidManifest.xml (example).

iOS

Ensure 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>

If you want to launch your app through an NFC tag, please take a look at the Core NFC documentation. The NFC tag requires a URI record (see createNdefUriRecord(...)) that must contain either a universal link (see Deep Linking with Universal and App Links) or a supported URL scheme.

Configuration

No configuration required for this plugin.

Usage

import { Nfc, NfcUtils, NfcTagTechType } from '@capawesome-team/capacitor-nfc';

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

const write = async () => {
  const record = createNdefTextRecord();

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

  await Nfc.startScanSession();
};

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

    Nfc.startScanSession();
  });
};

const makeReadOnly = async () => {
  Nfc.addListener('nfcTagScanned', async (event) => {
    await Nfc.makeReadOnly();
  });

  await Nfc.startScanSession();
};

const erase = async () => {
  Nfc.addListener('nfcTagScanned', async (event) => {
    await Nfc.erase();
  });

  await Nfc.startScanSession();
};

const format = async () => {
  Nfc.addListener('nfcTagScanned', async (event) => {
    await Nfc.format();
  });

  await Nfc.startScanSession();
};

const isSupported = async () => {
  const { isSupported } = await Nfc.isSupported();
  return isSupported;
};

const isEnabled = async () => {
  const { isEnabled } = await Nfc.isEnabled();
  return isEnabled;
};

const openSettings = async () => {
  await Nfc.openSettings();
};

const checkPermissions = async () => {
  const { nfc } = await Nfc.checkPermissions();
  return nfc;
};

const requestPermissions = async () => {
  const { nfc } = await Nfc.requestPermissions();
  return nfc;
};

const removeAllListeners = async () => {
  await Nfc.removeAllListeners();
};

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

  await Nfc.startScanSession();
};

API

startScanSession(...)
stopScanSession(...)
write(...)
makeReadOnly()
erase()
format()
transceive(...)
isSupported()
isEnabled()
openSettings()
checkPermissions()
requestPermissions()
addListener('nfcTagScanned', ...)
addListener('scanSessionCanceled', ...)
addListener('scanSessionError', ...)
removeAllListeners()
Interfaces
Type Aliases
Enums

startScanSession(...)

startScanSession(options?: StartScanSessionOptions | undefined) => Promise<void>

Start a scan session. Only one session can be active at a time.

On iOS, this will trigger the NFC Reader Session alert.

Param	Type
`options`	`StartScanSessionOptions`

Since: 0.0.1

stopScanSession(...)

stopScanSession(options?: StopScanSessionOptions | undefined) => Promise<void>

Stop the active scan session.

Param	Type
`options`	`StopScanSessionOptions`

Since: 0.0.1