@trentrand/capacitor-nfc

@trentrand/capacitor-nfc

Capacitor plugin to scan NFC tags

Install

npm install @trentrand/capacitor-nfc
npx cap sync

Xcode project prerequisites

iOS Configuration

Attempting to use this plugin on iOS without proper configuration in Xcode will result in an immediate app crash when NFCNDEFReaderSession.begin() is called. To prevent this:

• Enable NFC capabilities in Xcode and configure entitlements

  • In Xcode, click on your project in the navigator
  • Select your target
  • Click "Signing & Capabilities"
  • Click "+ Capability"
  • Add "Near Field Communication Tag Reading"
  • Verify the entitlements file now contains:

    <key>com.apple.developer.nfc.readersession.formats</key>
    <array>
        <string>TAG</string>
    </array>
    

• Add NFC usage description to Info.plist

<key>NFCReaderUsageDescription</key>
<string>Describe why your app needs NFC access</string>

• Ensure your Apple Developer account has NFC capabilities enabled in the Apple Developer portal. This requires a paid membership.

API

• startScan(...)
• stopScan()
• write(...)
• isEnabled()
• addListener('nfcTagRead', ...)
• removeAllListeners()
• Interfaces

startScan(...)

startScan(options?: NFCScanOptions | undefined) => Promise<void>

Start scanning for NFC tags.

Param	Type	Description
options	NFCScanOptions	Optional scan configuration

stopScan()

stopScan() => Promise<void>

Stop scanning for NFC tags.

write(...)

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

Write data to an NFC tag.

Param	Type	Description
options	NFCWriteOptions	Write configuration including the records to write

isEnabled()

isEnabled() => Promise<{ enabled: boolean; }>

Check if NFC is available and enabled on the device.

Returns: Promise<{ enabled: boolean; }>

addListener('nfcTagRead', ...)

addListener(eventName: 'nfcTagRead', listenerFunc: (event: NFCReadEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Add a listener for NFC events.

Param	Type	Description
eventName	'nfcTagRead'	Name of the event to listen for
listenerFunc	(event: NFCReadEvent) => void	Callback function

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for NFC events.

Interfaces

NFCScanOptions

Prop	Type
timeout	number

NFCWriteOptions

Prop	Type
records	NFCRecord[]
timeout	number

NFCRecord

Prop	Type
recordType	string
mediaType	string
data	DataView

DataView

Prop	Type
buffer	ArrayBuffer
byteLength	number
byteOffset	number

Method	Signature	Description
getFloat32	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Float32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getFloat64	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Float64 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt8	(byteOffset: number) => number	Gets the Int8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt16	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Int16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt32	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Int32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint8	(byteOffset: number) => number	Gets the Uint8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint16	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Uint16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint32	(byteOffset: number, littleEndian?: boolean | undefined) => number	Gets the Uint32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
setFloat32	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Float32 value at the specified byte offset from the start of the view.
setFloat64	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Float64 value at the specified byte offset from the start of the view.
setInt8	(byteOffset: number, value: number) => void	Stores an Int8 value at the specified byte offset from the start of the view.
setInt16	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Int16 value at the specified byte offset from the start of the view.
setInt32	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Int32 value at the specified byte offset from the start of the view.
setUint8	(byteOffset: number, value: number) => void	Stores an Uint8 value at the specified byte offset from the start of the view.
setUint16	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Uint16 value at the specified byte offset from the start of the view.
setUint32	(byteOffset: number, value: number, littleEndian?: boolean | undefined) => void	Stores an Uint32 value at the specified byte offset from the start of the view.

ArrayBuffer

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

Prop	Type	Description
byteLength	number	Read-only. The length of the ArrayBuffer (in bytes).

Method	Signature	Description
slice	(begin: number, end?: number | undefined) => ArrayBuffer	Returns a section of an ArrayBuffer.

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

NFCReadEvent

Prop	Type
message	NFCMessage
serialNumber	string

NFCMessage

Prop	Type
records	NFCRecord[]