@capawesome-team/capacitor-nfc¶

Capacitor plugin for reading and writing NFC tags.

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

Guides¶

Announcing the Capacitor NFC Plugin

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¶

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';
import { Capacitor } from '@capacitor/core';

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

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

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

    Nfc.startScanSession();
  });
};

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

    Nfc.startScanSession();
  });
};

const readSignature = async () => {
  return new Promise((resolve) => {
    Nfc.addListener('nfcTagScanned', async (event) => {
      if (Capacitor.getPlatform() === 'android') {
        // 1. Connect to the tag.
        await Nfc.connect({ techType: NfcTagTechType.NfcA }); 
        // 2. Send one or more commands to the tag and receive the response.
        const result = await Nfc.transceive({ data: [60, 0] });
        // 3. Close the connection to the tag.
        await Nfc.close();
        await Nfc.stopScanSession();
        resolve(response);
      } else {
        // 1. Send one or more commands to the tag and receive the response.
        const result = await Nfc.transceive({ techType: NfcTagTechType.NfcA, data: [60, 0] });
        await Nfc.stopScanSession();
        resolve(response);
      }
    });

    Nfc.startScanSession();
  });
};

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

    Nfc.startScanSession();
  });
};

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

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

API¶

startScanSession(...)
stopScanSession(...)
write(...)
makeReadOnly()
erase()
format()
transceive(...)
connect(...)
close()
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.

Stop the session as soon as you are done using stopScanSession(...).

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

write(...)¶

write(options: WriteOptions) => Promise<void>

Write to a NFC tag.

This method must be called from within a nfcTagScanned handler.

Param	Type
`options`	`WriteOptions`

Since: 0.0.1

makeReadOnly()¶

makeReadOnly() => Promise<void>

Make a NFC tag readonly.

This method must be called from within a nfcTagScanned handler.

Attention: This is permanent and can not be undone.

Since: 0.0.1

erase()¶

erase() => Promise<void>

Erase the NFC tag by writing an empty NDEF message.

This method must be called from within a nfcTagScanned handler.

Since: 0.3.0

format()¶

format() => Promise<void>

Format the NFC tag as NDEF and write an empty NDEF message.

This method must be called from within a nfcTagScanned handler.

Only available on Android.

Since: 0.3.0

transceive(...)¶

transceive(options: TransceiveOptions) => Promise<TransceiveResult>

Send raw command to the tag and receive the response.

This method must be called from within a nfcTagScanned handler.

On Android, the tag must be connected with connect() first.

⚠️ Experimental: This method could not be tested extensively yet. Please let us know if you discover any issues!

⚠️ Attention: A bad command can damage the tag forever. Please read the Android and iOS documentation linked below first.

More information on how to use this method on Android: https://bit.ly/3ywSkvT

More information on how to use this method on iOS with... - ISO 15693-3: https://apple.co/3Lliaum - FeliCa: https://apple.co/3LpvRs6

Only available on Android and iOS.

Param	Type
`options`	`TransceiveOptions`

Returns: Promise<TransceiveResult>

Since: 0.3.0

connect(...)¶

connect(options: ConnectOptions) => Promise<void>

Connect to the tag and enable I/O operations.

This method must be called from within a nfcTagScanned handler.

Only available on Android.

Param	Type
`options`	`ConnectOptions`

Since: 6.0.0

close()¶

close() => Promise<void>

Close the connection to the tag.

This method must be called from within a nfcTagScanned handler.

Only available on Android.

Since: 6.0.0

isSupported()¶

isSupported() => Promise<IsSupportedResult>

Returns whether or not NFC is supported.

Returns: Promise<IsSupportedResult>

Since: 0.0.1

isEnabled()¶

isEnabled() => Promise<IsEnabledResult>

Returns whether or not NFC is enabled.

Only available on Android.

Returns: Promise<IsEnabledResult>

Since: 0.0.1

openSettings()¶

openSettings() => Promise<void>

Opens the NFC device settings so that the user can enable or disable NFC.

Only available on Android.

Since: 0.0.1

checkPermissions()¶

checkPermissions() => Promise<PermissionResult>

Check permission for reading and writing NFC tags.

This method is only needed on Web. On Android and iOS, granted is always returned.

Returns: Promise<PermissionResult>

Since: 0.0.1

requestPermissions()¶

requestPermissions() => Promise<PermissionResult>

Request permission for reading and writing NFC tags.

This method is only needed on Web. On Android and iOS, granted is always returned.

Returns: Promise<PermissionResult>

Since: 0.0.1

addListener('nfcTagScanned', ...)¶

addListener(eventName: 'nfcTagScanned', listenerFunc: (event: NfcTagScannedEvent) => void) => Promise<PluginListenerHandle>

Called when a new NFC tag is scanned.

Param	Type
`eventName`	`'nfcTagScanned'`
`listenerFunc`	`(event: NfcTagScannedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('scanSessionCanceled', ...)¶

addListener(eventName: 'scanSessionCanceled', listenerFunc: () => void) => Promise<PluginListenerHandle>

Called when the scan session was canceled.

Only available on iOS.

Param	Type
`eventName`	`'scanSessionCanceled'`
`listenerFunc`	`() => void`

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('scanSessionError', ...)¶

addListener(eventName: 'scanSessionError', listenerFunc: (event: ScanSessionErrorEvent) => void) => Promise<PluginListenerHandle>

Called when an error occurs during the scan session.

Param	Type
`eventName`	`'scanSessionError'`
`listenerFunc`	`(event: ScanSessionErrorEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

removeAllListeners()¶

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

Interfaces¶

StartScanSessionOptions¶

Prop	Type	Description	Default	Since
`alertMessage`	`string`	A custom message, which is displayed in the NFC Reader Session alert. Only available on iOS.		0.0.1
`techTypes`	`NfcTagTechType[]`	The NFC tag technologies to filter on in this session. Only available on Android.		0.0.1
`mimeTypes`	`string[]`	Mime types to filter on in this session. Only available on Android.		0.0.1
`pollingOptions`	`PollingOption[]`	Type of tags to detect during a polling sequence. Only available on iOS.	`[PollingOption.iso14443, PollingOption.iso15693]`	0.2.0

StopScanSessionOptions¶

Prop	Type	Description	Since
`errorMessage`	`string`	A custom error message, which is displayed in the NFC Reader Session alert. Only available on iOS.	0.0.1

WriteOptions¶

Prop	Type	Description	Since
`message`	`NdefMessage`	The NDEF message to write.	0.0.1

NdefMessage¶

Prop	Type	Description	Since
`records`	`NdefRecord[]`	The records of the NDEF message.	0.0.1

NdefRecord¶

Prop	Type	Description	Since
`id`	`number[]`	The record identifier as byte array.	0.0.1
`payload`	`number[]`	The payload field data as byte array.	0.0.1
`tnf`	`TypeNameFormat`	The record type name format which indicates the structure of the value of the `type` field.	0.0.1
`type`	`number[]`	The type of the record payload. This should be used in conjunction with the `tnf` field to determine the payload format.	0.0.1

TransceiveResult¶

Prop	Type	Description	Since
`response`	`number[]`	Bytes received in response.	0.3.0

TransceiveOptions¶

Prop	Type	Description	Since
`techType`	`NfcTagTechType`	The NFC tag technology to connect with. Only available on iOS.	0.3.0
`data`	`number[]`	Bytes to send.	0.3.0
`iso15693RequestFlags`	`Iso15693RequestFlag[]`	The request flags for the NFC tag technology type `NfcV` (ISO 15693-3). Only available on iOS 14+	0.3.0
`iso15693CommandCode`	`number`	The custom command code defined by the IC manufacturer for the NFC tag technology type `NfcV` (ISO 15693-3). Valid range is 0xA0 to 0xDF inclusively, 0x23 is also supported. Only available on iOS 14+	0.3.0

ConnectOptions¶

Prop	Type	Description	Since
`techType`	`NfcTagTechType`	The NFC tag technology to connect with. Only available on Android.	6.0.0

IsSupportedResult¶

Prop	Type	Since
`isSupported`	`boolean`	0.0.1

IsEnabledResult¶

Prop	Type	Since
`isEnabled`	`boolean`	0.0.1

PermissionResult¶

Prop	Type	Description	Since
`nfc`	`PermissionState`	Permission state for reading and writing NFC tags.	0.0.1

PluginListenerHandle¶

Prop	Type
`remove`	`() => Promise<void>`

NfcTagScannedEvent¶

Prop	Type	Description	Since
`nfcTag`	`NfcTag`	The scanned NFC tag.	0.0.1

NfcTag¶

Prop	Type	Description	Since
`atqa`	`number[]`	The ATQA/SENS_RES bytes of an NFC A tag. Only available on Android.	0.0.1
`applicationData`	`number[]`	The Application Data bytes from ATQB/SENSB_RES of an NFC B tag. Only available on Android and iOS.	0.0.1
`barcode`	`number[]`	The barcode bytes of an NfcBarcode tag. Only available on Android.	0.0.1
`canMakeReadOnly`	`boolean`	Whether the NDEF tag can be made read-only or not. Only available on Android.	0.0.1
`dsfId`	`number[]`	The DSF ID bytes of an NFC V tag. Only available on Android.	0.0.1
`hiLayerResponse`	`number[]`	The higher layer response bytes of an ISO-DEP tag. Only available on Android.	0.0.1
`historicalBytes`	`number[]`	The historical bytes of an ISO-DEP tag. Only available on Android and iOS.	0.0.1
`id`	`number[]`	The tag identifier (low level serial number) which is used for anti-collision and identification.	0.0.1
`isWritable`	`boolean`	Whether the NDEF tag is writable or not. Only available on Android and iOS.	0.0.1
`manufacturer`	`number[]`	The Manufacturer bytes of an NFC F tag. Only available on Android and iOS.	0.0.1
`maxSize`	`number`	The maximum NDEF message size in bytes. Only available on Android and iOS.	0.0.1
`message`	`NdefMessage`	The NDEF-formatted message.	0.0.1
`protocolInfo`	`number[]`	The Protocol Info bytes from ATQB/SENSB_RES of an NFC B tag. Only available on Android.	0.0.1
`responseFlags`	`number[]`	The Response Flag bytes of an NFC V tag. Only available on Android.	0.0.1
`sak`	`number[]`	The SAK/SEL_RES bytes of an NFC A tag. Only available on Android.	0.0.1
`systemCode`	`number[]`	The System Code bytes of an NFC F tag. Only available on Android and iOS.	0.0.1
`techTypes`	`NfcTagTechType[]`	The technologies available in this tag. Only available on Android and iOS.	0.0.1
`type`	`NfcTagType`	The NDEF tag type. Only available on Android and iOS.	0.0.1

ScanSessionErrorEvent¶

Prop	Type	Description	Since
`message`	`string`	The error message.	0.0.1

Type Aliases¶

PermissionState¶

"denied" | "granted" | "prompt"

Enums¶

NfcTagTechType¶

Members	Value	Description	Since
`NfcA`	`'NFC_A'`	The NFC-A (ISO 14443-3A) tag technology. Only available on Android.	0.0.1
`NfcB`	`'NFC_B'`	The NFC-B (ISO 14443-3B) tag technology. Only available on Android.	0.0.1
`NfcF`	`'NFC_F'`	The NFC-F (JIS 6319-4) tag technology. Only available on Android and iOS.	0.0.1
`NfcV`	`'NFC_V'`	The NFC-V (ISO 15693) tag technology. Only available on Android and iOS.	0.0.1
`IsoDep`	`'ISO_DEP'`	The ISO-DEP (ISO 14443-4) tag technology. Only available on Android.	0.0.1
`Iso7816`	`'ISO_7816'`	The ISO 7816 tag technology. Only available on iOS.	5.1.0
`Ndef`	`'NDEF'`	The NDEF tag technology. Only available on Android.	0.0.1
`MifareClassic`	`'MIFARE_CLASSIC'`	The MIFARE Classic tag technology. Only available on Android.	0.0.1
`MifareDesfire`	`'MIFARE_DESFIRE'`	The MIFARE Desfire tag technology. Only available on iOS.	5.1.0
`MifarePlus`	`'MIFARE_PLUS'`	The MIFARE Plus tag technology. Only available on iOS.	5.1.0
`MifareUltralight`	`'MIFARE_ULTRALIGHT'`	The MIFARE Ultralight tag technology. Only available on Android and iOS.	0.0.1
`NfcBarcode`	`'NFC_BARCODE'`	The technology of a tag containing just a barcode. Only available on Android.	0.0.1
`NdefFormatable`	`'NDEF_FORMATABLE'`	The NDEF formatable tag technology. Only available on Android.	0.0.1

PollingOption¶

Members	Value	Description	Since
`iso14443`	`'iso14443'`	The option for detecting ISO 7816-compatible and MIFARE tags.	0.2.0
`iso15693`	`'iso15693'`	The option for detecting ISO 15693 tags.	0.2.0
`iso18092`	`'iso18092'`	The option for detecting FeliCa tags.	0.2.0

TypeNameFormat¶

Members	Value	Description	Since
`Empty`	`0`	An empty record with no type or payload.	0.0.1
`WellKnown`	`1`	A predefined type defined in the RTD specification of the NFC Forum.	0.0.1
`MimeMedia`	`2`	An Internet media type as defined in RFC 2046.	0.0.1
`AbsoluteUri`	`3`	A URI as defined in RFC 3986.	0.0.1
`External`	`4`	A user-defined value that is based on the rules of the NFC Forum Record Type Definition specification.	0.0.1
`Unknown`	`5`	Type is unknown.	0.0.1
`Unchanged`	`6`	Indicates the payload is an intermediate or final chunk of a chunked NDEF Record.	0.0.1

Iso15693RequestFlag¶

Members	Value	Since
`address`	`'address'`	0.3.0
`commandSpecificBit8`	`'commandSpecificBit8'`	0.3.0
`dualSubCarriers`	`'dualSubCarriers'`	0.3.0
`highDataRate`	`'highDataRate'`	0.3.0
`option`	`'option'`	0.3.0
`protocolExtension`	`'protocolExtension'`	0.3.0
`select`	`'select'`	0.3.0

NfcTagType¶

Members	Value	Description	Since
`NfcForumType1`	`'NFC_FORUM_TYPE_1'`	Only available on Android.	0.0.1
`NfcForumType2`	`'NFC_FORUM_TYPE_2'`	Only available on Android.	0.0.1
`NfcForumType3`	`'NFC_FORUM_TYPE_3'`	Only available on Android and iOS.	0.0.1
`NfcForumType4`	`'NFC_FORUM_TYPE_4'`	Only available on Android.	0.0.1
`MifareClassic`	`'MIFARE_CLASSIC'`	Only available on Android.	0.0.1
`MifareDesfire`	`'MIFARE_DESFIRE'`		0.0.1
`MifarePlus`	`'MIFARE_PLUS'`	Only available on Android.	0.0.1
`MifarePro`	`'MIFARE_PRO'`	Only available on Android.	0.0.1
`MifareUltralight`	`'MIFARE_ULTRALIGHT'`	Only available on Android.	0.0.1
`MifareUltralightC`	`'MIFARE_ULTRALIGHT_C'`	Only available on Android.	0.0.1

Utils¶

See docs/utils/README.md.

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.