0.3.0 • Published 6 months ago
@trentrand/capacitor-nfc v0.3.0
@trentrand/capacitor-nfc
Capacitor plugin to scan NFC tags
Install
npm install @trentrand/capacitor-nfc
npx cap syncXcode 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> & PluginListenerHandleAdd 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[] |