@tauri-apps/plugin-nfc

Read and write NFC tags on Android and iOS.

This plugin is mobile only, the APIs reject on desktop platforms.

Functions

isAvailable()

function isAvailable(): Promise<boolean>;

Defined in: plugins/nfc/guest-js/index.ts:464

Checks whether NFC is supported by the device and currently usable by the app.

Resolves to false on Android when the device has no NFC adapter or NFC is disabled in the device settings, and on iOS when the NFCReaderUsageDescription entry is missing from the Info.plist file or NFC tag reading is unavailable.

Example

import { isAvailable } from '@tauri-apps/plugin-nfc';
const canScan = await isAvailable();

Returns

Promise<boolean>

A promise resolving to whether NFC is available on the device.

Since

2.0.0

record()

function record(
   format: NFCTypeNameFormat,
   kind: string | number[],
   id: string | number[],
   payload: string | number[]
): NFCRecord;

Defined in: plugins/nfc/guest-js/index.ts:242

Creates an NDEF record with the given type name format, type, identifier and payload.

Strings are encoded as UTF-8 byte arrays.

Example

import { record, NFCTypeNameFormat, write } from '@tauri-apps/plugin-nfc';
const mimeRecord = record(NFCTypeNameFormat.Media, 'text/plain', '', 'hello world');
await write([mimeRecord], { kind: { type: 'ndef' } });

Parameters

Parameter	Type	Description
`format`	`NFCTypeNameFormat`	The Type Name Format (TNF) of the record.
`kind`	`string` \| `number`[]	The record type, interpreted according to `format`.
`id`	`string` \| `number`[]	The record identifier. Use an empty string or array when the record has none.
`payload`	`string` \| `number`[]	The record payload.

Returns

NFCRecord

The NDEF record, ready to be written with write.

Since

2.0.0

scan()

function scan(kind: ScanKind, options?: ScanOptions): Promise<Tag>;

Defined in: plugins/nfc/guest-js/index.ts:404

Scans an NFC tag, resolving when a tag matching the given filters is read.

See https://developer.android.com/develop/connectivity/nfc/nfc#ndef for more information.

Example

import { scan } from '@tauri-apps/plugin-nfc';
const tag = await scan({ type: 'tag' });

Parameters

Parameter	Type	Description
`kind`	`ScanKind`	The kind of scan to perform, which defines how tags are matched.
`options?`	`ScanOptions`	Additional scan options such as the iOS UI messages and whether the session must be kept alive for a following write call.

Returns

Promise<Tag>

A promise resolving to the tag that has been scanned.

Since

2.0.0

textRecord()

function textRecord(
   text: string,
   id?: string | number[],
   language?: string
): NFCRecord;

Defined in: plugins/nfc/guest-js/index.ts:281

Creates an NDEF well known text record (RTD_TEXT).

The payload is the UTF-8 encoded text prefixed by the language code and by a status byte holding the length of that language code.

Example

import { textRecord, write } from '@tauri-apps/plugin-nfc';
await write([textRecord('hello world')], { kind: { type: 'ndef' } });

Parameters

Parameter	Type	Default value	Description
`text`	`string`	`undefined`	The text to store in the record.
`id?`	`string` \| `number`[]	`undefined`	The record identifier. Defaults to an empty identifier.
`language?`	`string`	`'en'`	The IANA language code of the text. Defaults to `en`.

Returns

NFCRecord

The NDEF record, ready to be written with write.

Since

2.0.0

uriRecord()

function uriRecord(uri: string, id?: string | number[]): NFCRecord;

Defined in: plugins/nfc/guest-js/index.ts:372

Creates an NDEF well known URI record (RTD_URI).

The URI is encoded with the NDEF URI abbreviation scheme: a known prefix such as https:// is replaced by the identifier code byte that starts the payload.

Example

import { uriRecord, write } from '@tauri-apps/plugin-nfc';
await write([uriRecord('https://tauri.app')], { kind: { type: 'ndef' } });

Parameters

Parameter	Type	Description
`uri`	`string`	The URI to store in the record.
`id?`	`string` \| `number`[]	The record identifier. Defaults to an empty identifier.

Returns

NFCRecord

The NDEF record, ready to be written with write.

Since

2.0.0

write()

function write(records: NFCRecord[], options?: WriteOptions): Promise<void>;

Defined in: plugins/nfc/guest-js/index.ts:432

Write to an NFC tag.

If you did not previously call scan with ScanOptions.keepSessionAlive set to true, it will first scan the tag then write to it.

Example

import { uriRecord, write } from '@tauri-apps/plugin-nfc';
await write([uriRecord('https://tauri.app')], { kind: { type: 'ndef' } });

Parameters

Parameter	Type	Description
`records`	`NFCRecord`[]	The NDEF records to write to the tag.
`options?`	`WriteOptions`	Additional write options such as the kind of scan used to find the tag and the iOS UI messages.

Returns

Promise<void>

Since

2.0.0

Enumerations

NFCTypeNameFormat

Defined in: plugins/nfc/guest-js/index.ts:151

The Type Name Format (TNF) of an NDEF record, which defines how the record type is interpreted.

Enumeration Members

Enumeration Member	Value	Description	Defined in
`AbsoluteURI`	`3`	The record type is an absolute URI as defined in RFC 3986.	plugins/nfc/guest-js/index.ts:162
`Empty`	`0`	The record is empty: type, identifier and payload must be empty.	plugins/nfc/guest-js/index.ts:153
`Media`	`2`	The record type is a MIME media type as defined in RFC 2046, e.g. `text/plain`.	plugins/nfc/guest-js/index.ts:160
`NfcExternal`	`4`	The record type is an NFC Forum external type, i.e. a type namespaced by its issuer.	plugins/nfc/guest-js/index.ts:164
`NfcWellKnown`	`1`	The record type is an NFC Forum well known type, defined by a Record Type Definition (RTD) such as RTD_TEXT or RTD_URI.	plugins/nfc/guest-js/index.ts:158
`Unchanged`	`6`	The record is a middle or last chunk of a chunked record and inherits the type of the first chunk, so its own type must be empty.	plugins/nfc/guest-js/index.ts:174
`Unknown`	`5`	The record type is unknown: the type must be empty and the payload interpretation is left to the application.	plugins/nfc/guest-js/index.ts:169

TechKind

Defined in: plugins/nfc/guest-js/index.ts:48

The NFC technologies a tag can support, mirroring the android.nfc.tech classes.

Android only, used by the techLists filter of an ndef ScanKind.

Enumeration Members

Enumeration Member	Value	Description	Defined in
`IsoDep`	`0`	ISO-DEP (ISO 14443-4) properties and I/O operations.	plugins/nfc/guest-js/index.ts:50
`MifareClassic`	`1`	MIFARE Classic properties and I/O operations.	plugins/nfc/guest-js/index.ts:52
`MifareUltralight`	`2`	MIFARE Ultralight and MIFARE Ultralight C properties and I/O operations.	plugins/nfc/guest-js/index.ts:54
`Ndef`	`3`	NDEF data and operations on tags that are already formatted as NDEF.	plugins/nfc/guest-js/index.ts:56
`NdefFormatable`	`4`	Formatting operations on tags that can be formatted as NDEF but are not yet.	plugins/nfc/guest-js/index.ts:58
`NfcA`	`5`	NFC-A (ISO 14443-3A) properties and I/O operations.	plugins/nfc/guest-js/index.ts:60
`NfcB`	`6`	NFC-B (ISO 14443-3B) properties and I/O operations.	plugins/nfc/guest-js/index.ts:62
`NfcBarcode`	`7`	NFC Barcode (Kovio NFC Barcode) properties and I/O operations.	plugins/nfc/guest-js/index.ts:64
`NfcF`	`8`	NFC-F (JIS 6319-4) properties and I/O operations.	plugins/nfc/guest-js/index.ts:66
`NfcV`	`9`	NFC-V (ISO 15693) properties and I/O operations.	plugins/nfc/guest-js/index.ts:68

Interfaces

NFCRecord

Defined in: plugins/nfc/guest-js/index.ts:207

An NDEF record to be written to a tag.

Use record, textRecord or uriRecord to create one.

Properties

Property	Type	Description	Defined in
`format`	`NFCTypeNameFormat`	The Type Name Format (TNF) of the record.	plugins/nfc/guest-js/index.ts:209
`id`	`number`[]	The record identifier. Can be empty.	plugins/nfc/guest-js/index.ts:217
`kind`	`number`[]	The record type, interpreted according to NFCRecord.format. For well known records this is a Record Type Definition (RTD) value such as RTD_TEXT or RTD_URI.	plugins/nfc/guest-js/index.ts:215
`payload`	`number`[]	The record payload bytes.	plugins/nfc/guest-js/index.ts:219

ScanOptions

Defined in: plugins/nfc/guest-js/index.ts:119

Options for the scan function.

Properties

Property	Type	Description	Defined in
`keepSessionAlive?`	`boolean`	Whether the connection to the scanned tag must be kept open after the scan resolves, so that a following write call writes to that tag instead of scanning a new one. Defaults to `false`.	plugins/nfc/guest-js/index.ts:125
`message?`	`string`	Message displayed in the UI. iOS only.	plugins/nfc/guest-js/index.ts:127
`successMessage?`	`string`	Message displayed in the UI when the message has been read. iOS only.	plugins/nfc/guest-js/index.ts:129

Tag

Defined in: plugins/nfc/guest-js/index.ts:193

An NFC tag that has been scanned.

Properties

Property	Type	Description	Defined in
`id`	`number`[]	The tag identifier bytes, as reported by the operating system.	plugins/nfc/guest-js/index.ts:195
`kind`	`string`[]	The technologies the tag supports, e.g. `["android.nfc.tech.Ndef"]` on Android.	plugins/nfc/guest-js/index.ts:197
`records`	`TagRecord`[]	The NDEF records stored on the tag. Empty when the tag holds no NDEF message.	plugins/nfc/guest-js/index.ts:199

TagRecord

Defined in: plugins/nfc/guest-js/index.ts:178

An NDEF record read from a scanned tag.

Properties

Property	Type	Description	Defined in
`id`	`number`[]	The record identifier bytes. Can be empty.	plugins/nfc/guest-js/index.ts:187
`kind`	`number`[]	The record type bytes.	plugins/nfc/guest-js/index.ts:185
`payload`	`number`[]	The record payload bytes.	plugins/nfc/guest-js/index.ts:189
`tnf`	`NFCTypeNameFormat`	The Type Name Format (TNF) of the record, which defines how TagRecord.kind is interpreted.	plugins/nfc/guest-js/index.ts:183

UriFilter

Defined in: plugins/nfc/guest-js/index.ts:34

Filters the tags to scan by the URI of their payload.

Every property is optional and only the ones that are set take part in the filter. Android only, the iOS implementation ignores this filter.

Properties

Property	Type	Description	Defined in
`host?`	`string`	Only match URIs with this authority (host), e.g. `tauri.app`.	plugins/nfc/guest-js/index.ts:38
`pathPrefix?`	`string`	Only match URIs whose path starts with this prefix, e.g. `/docs`.	plugins/nfc/guest-js/index.ts:40
`scheme?`	`string`	Only match URIs with this scheme, e.g. `https`.	plugins/nfc/guest-js/index.ts:36

WriteOptions

Defined in: plugins/nfc/guest-js/index.ts:133

Options for the write function.

Properties

Property	Type	Description	Defined in
`kind?`	`ScanKind`	The kind of scan to perform to find the tag to write to. Required on Android unless a scan session is kept alive.	plugins/nfc/guest-js/index.ts:138
`message?`	`string`	Message displayed in the UI when reading the tag. iOS only.	plugins/nfc/guest-js/index.ts:140
`successfulReadMessage?`	`string`	Message displayed in the UI when the tag has been read. iOS only.	plugins/nfc/guest-js/index.ts:142
`successMessage?`	`string`	Message displayed in the UI when the message has been written. iOS only.	plugins/nfc/guest-js/index.ts:144

Type Aliases

ScanKind

type ScanKind =
  | {
  mimeType?: string;
  type: "tag";
  uri?: UriFilter;
}
  | {
  mimeType?: string;
  techLists?: TechKind[][];
  type: "ndef";
  uri?: UriFilter;
};

Defined in: plugins/nfc/guest-js/index.ts:76

The kind of scan to perform, which defines which tags are matched.

Use tag to match any discovered tag and ndef to only match tags carrying an NDEF message.

Union Members

Type Literal

{
  mimeType?: string;
  type: "tag";
  uri?: UriFilter;
}

Name	Type	Description	Defined in
`mimeType?`	`string`	Only match tags whose payload has this MIME type, e.g. `text/plain`. Android only.	plugins/nfc/guest-js/index.ts:83
`type`	`"tag"`	Matches any tag that is discovered, whether it carries an NDEF message or not.	plugins/nfc/guest-js/index.ts:79
`uri?`	`UriFilter`	Only match tags whose payload URI matches this filter. Android only.	plugins/nfc/guest-js/index.ts:81

Type Literal

{
  mimeType?: string;
  techLists?: TechKind[][];
  type: "ndef";
  uri?: UriFilter;
}

Name	Type	Description	Defined in
`mimeType?`	`string`	Only match tags whose NDEF payload has this MIME type, e.g. `text/plain`. Android only.	plugins/nfc/guest-js/index.ts:94
`techLists?`	`TechKind`[][]	Each of the tech-lists is considered independently and the activity is considered a match if any single tech-list matches the tag that was discovered. This provides AND and OR semantics for filtering desired techs. See https://developer.android.com/reference/android/nfc/NfcAdapter#ACTION_TECH_DISCOVERED for more information. Examples `import type { TechKind } from "@tauri-apps/plugin-nfc" const techLists = [ // capture anything using NfcF [TechKind.NfcF], // capture all MIFARE Classics with NDEF payloads [TechKind.NfcA, TechKind.MifareClassic, TechKind.Ndef] ]`	plugins/nfc/guest-js/index.ts:115
`type`	`"ndef"`	Only matches tags that carry an NDEF message.	plugins/nfc/guest-js/index.ts:87
`uri?`	`UriFilter`	Only match tags whose NDEF payload URI matches this filter. Android only.	plugins/nfc/guest-js/index.ts:89

Variables

RTD_TEXT

const RTD_TEXT: number[];

Defined in: plugins/nfc/guest-js/index.ts:20

Record Type Definition (RTD) of an NDEF well known text record, the "T" (0x54) byte.

Since

2.0.0

RTD_URI

const RTD_URI: number[];

Defined in: plugins/nfc/guest-js/index.ts:26

Record Type Definition (RTD) of an NDEF well known URI record, the "U" (0x55) byte.

Since

2.0.0

Support on Open Collective Sponsor on GitHub