--- title: Capacitor NFC Plugin for Android, iOS & Web description: Capacitor plugin for NFC tag reading, writing, and emulation. Supports Android, iOS, and Web with advanced features like HCE and raw command handling. tags: - Insiders - Android - iOS - Web search: boost: 2 faq: true github_repo: capawesome-team/capacitor-plugins sponsor: name: NFC21 image: /docs/assets/images/sponsors/nfc21-logo.png url: https://nfc21.de/?_locale=en&utm_source=capawesome&utm_medium=referral&utm_campaign=capawesome --- # Capacitor NFC Plugin Capacitor plugin for NFC tag reading, writing, and emulation. Supports Android, iOS, and Web with advanced features like HCE and raw command handling.
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features The Capacitor NFC plugin is one of the most complete NFC solutions for Capacitor apps. Here are some of the key features: - 🖥️ **Cross-platform**: Supports Android, iOS and Web. - 🔄 **NDEF**: Read and write NFC Data Exchange Format (NDEF) messages. - 📳 **HCE**: Emulate an NFC card that other devices can interact with. - ⌘ **Raw Commands**: Send raw commands to an NFC tag and receive the response. - 🛠️ **Utils**: Utility functions to make your life easier. - ⚔️ **Battle-Tested**: Used in more than 500 projects. - 📚 **Documentation**: Comprehensive documentation to help you get started. - 🤝 **Compatibility**: Works alongside the [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/), [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/) and [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/) plugins. - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. - 🔁 **Up-to-date**: Always supports the latest Capacitor version. - ⭐️ **Support**: Priority support from the Capawesome Team. - ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The NFC plugin is typically used whenever an app needs to interact with NFC tags or readers, for example: - **Inventory and asset tracking**: Scan NFC tags to read their identifiers and NDEF messages, for example to identify equipment or products. - **Tag provisioning**: Write NDEF messages such as text or URI records to tags and optionally make them permanently read-only. - **App launching**: Launch your app by scanning a tag containing a URI record, using an intent filter on Android or universal links on iOS. - **Smartcard communication**: Exchange raw commands such as APDUs with tags and smartcards using the `transceive(...)` method. - **Card emulation**: Emulate an NFC card on Android using Host Card Emulation (HCE) so that other devices can interact with it. - **Tap-to-pair onboarding**: Read a nearby device's identifier from an NFC tag, then connect to it over [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/) — no manual scanning or pairing UI needed. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | | 6.x.x | 6.x.x | Deprecated | ## Demo A working example can be found [here](https://github.com/capawesome-team/capacitor-nfc-demo). | Android | iOS | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Android Demo | iOS Demo | ## Guides - [Announcing the Capacitor NFC Plugin](https://capawesome.io/blog/announcing-the-capacitor-nfc-plugin/) - [Exploring the Capacitor NFC API](https://capawesome.io/blog/exploring-the-capacitor-nfc-api/) ## Installation This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: ``` npm config set @capawesome-team:registry https://npm.registry.capawesome.io npm config set //npm.registry.capawesome.io/:_authToken ``` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-nfc` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome-team/capacitor-nfc npx cap sync ``` ### Android #### Features Add the following element to your `AndroidManifest.xml` before or after the `application` tag: ```xml ``` Set the `android:required` attribute to `true` if your app can't function, or isn't designed to function, when NFC is not available on the device. If your app can function without NFC, set the `android:required` attribute to `false`. This will allow your app to be installed on devices that do not support NFC. #### Intent Filter If you want to launch your app through an NFC tag, please take a look at the [Android documentation](https://developer.android.com/guide/topics/connectivity/nfc/nfc#dispatching). There you will find which changes you have to apply to your `AndroidManifest.xml` ([example](https://developer.android.com/guide/topics/connectivity/nfc/nfc#ndef-disc)). #### Services To be able to use Host Card Emulation (HCE), you also need to add the following service **inside** the `application` tag in your `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`): ```xml ``` This meta-data tag points to an `apduservice.xml` file. The following is an example of such a file with a single AID group declaration containing two proprietary AIDs: ```xml ``` You can find more information about this in the [Android documentation](https://developer.android.com/develop/connectivity/nfc/hce#manifest-declaration). #### Proguard If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: ``` -keep class io.capawesome.capacitorjs.plugins.** { *; } ``` ### iOS #### Entitlements Ensure `Near Field Communication Tag Reading` and `NFC Scan` capabilities have been enabled in your application in Xcode. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information. This will also create or update the `ios/App/App/App.entitlements` file. Make sure it contains the following key to allow reading NFC tags: ```xml com.apple.developer.nfc.readersession.formats NDEF TAG ``` #### Privacy Descriptions Add the `NFCReaderUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why the app needs to use NFC: ```xml NFCReaderUsageDescription The app enables the reading and writing of various NFC tags. ``` #### Universal Links If you want to launch your app through an NFC tag, please take a look at the [Core NFC documentation](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032598). The NFC tag requires a [URI record](https://w3c.github.io/web-nfc/#uri-record) (see [`createNdefUriRecord(...)`](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/nfc/docs/utils#createndefurirecord)) that must contain either a universal link (see [Deep Linking with Universal and App Links](https://capacitorjs.com/docs/guides/deep-links)) or a [supported URL scheme](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032600). ## Configuration No configuration required for this plugin. ## Usage The following examples show how to read, write, make read-only, erase, and format NFC tags, send raw commands, check NFC support and permissions, and use Host Card Emulation. ### Read an NFC tag Start a scan session and listen for the `nfcTagScanned` event to receive the scanned tag. Only one session can be active at a time, so stop the session as soon as you are done. On iOS, starting a scan session triggers the NFC Reader Session alert: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const read = async () => { return new Promise((resolve) => { Nfc.addListener('nfcTagScanned', async (event) => { await Nfc.stopScanSession(); resolve(event.nfcTag); }); Nfc.startScanSession(); }); }; ``` ### Write to an NFC tag Create an NDEF record, for example with the `NfcUtils` class (see [Utils](#utils)), and write it to the tag from within the `nfcTagScanned` handler: ```typescript import { Nfc, NfcUtils } from '@capawesome-team/capacitor-nfc'; 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(); }); }; ``` ### Make an NFC tag read-only Use the `makeReadOnly()` method to write-protect a tag. **Attention**: This is permanent and cannot be undone: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const makeReadOnly = async () => { return new Promise((resolve) => { Nfc.addListener('nfcTagScanned', async (event) => { await Nfc.makeReadOnly(); await Nfc.stopScanSession(); resolve(); }); Nfc.startScanSession(); }); }; ``` ### Erase or format an NFC tag Use the `erase()` method to write an empty NDEF message to the tag, or the `format()` method to format the tag as NDEF first. The `format()` method is only available on Android: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; 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(); }); }; ``` ### Send raw commands to an NFC tag Use the `transceive(...)` method to send raw commands to the tag and receive the response. On Android, you must connect to the tag with `connect(...)` first and close the connection with `close()` afterwards. On iOS, pass the tag technology directly to `transceive(...)`. This method is only available on Android and iOS. The following example reads the signature of a tag: ```typescript import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc'; import { Capacitor } from '@capacitor/core'; 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(result); } 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(result); } }); Nfc.startScanSession(); }); }; ``` ### Check whether NFC is supported and enabled Use the `isSupported()` method to check whether the device supports NFC and the `isEnabled()` method to check whether NFC is enabled: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const isSupported = async () => { const { nfc } = await Nfc.isSupported(); return nfc; }; const isEnabled = async () => { const { isEnabled } = await Nfc.isEnabled(); return isEnabled; }; ``` ### Open the NFC device settings Open the NFC device settings so that the user can enable or disable NFC. Only available on Android: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const openSettings = async () => { await Nfc.openSettings(); }; ``` ### Check and request permissions Checking and requesting permissions is only needed on Web. On Android and iOS, `granted` is always returned: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const checkPermissions = async () => { const { nfc } = await Nfc.checkPermissions(); return nfc; }; const requestPermissions = async () => { const { nfc } = await Nfc.requestPermissions(); return nfc; }; ``` ### Remove all listeners Remove all listeners for this plugin when they are no longer needed: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const removeAllListeners = async () => { await Nfc.removeAllListeners(); }; ``` ### Advanced #### HCE Host Card Emulation (HCE) allows your device to emulate an NFC card that other devices can interact with. The first example below demonstrates how to send APDU commands from an NFC reader using the `transceive(...)` method: ```typescript import { Nfc, NfcTagTechType } from '@capawesome-team/capacitor-nfc'; import { Capacitor } from '@capacitor/core'; const sendApduCommands = async () => { return new Promise((resolve) => { Nfc.addListener('nfcTagScanned', async (event) => { // Define APDU commands const selectApdu = [0x00, 0xA4, 0x04, 0x00, 0x07, 0xF0, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x00]; const customApdu = [0x00, 0x01, 0x00, 0x00, 0x00]; // Connect to the tag (Android only) if (Capacitor.getPlatform() === 'android') { await Nfc.connect({ techType: NfcTagTechType.IsoDep }); } // Send SELECT APDU command const selectResponse = await Nfc.transceive({ techType: NfcTagTechType.Iso7816, data: selectApdu }); // Send custom APDU command const customResponse = await Nfc.transceive({ techType: NfcTagTechType.Iso7816, data: customApdu }); // Close the connection (Android only) if (Capacitor.getPlatform() === 'android') { await Nfc.close(); } // Stop the scan session await Nfc.stopScanSession(); resolve(); }); // Start the scan session Nfc.startScanSession(); }); }; ``` The second example below demonstrates how to respond to APDU commands sent by an NFC reader using the `commandReceived` event listener and the `respond(...)` method: ```typescript import { Nfc } from '@capawesome-team/capacitor-nfc'; const respondToApduCommands = async () => { // Listen for incoming APDU commands Nfc.addListener('commandReceived', async (event) => { // Parse the incoming command const command = event.data; // Check if it's a SELECT command if (command[0] === 0x00 && command[1] === 0xA4 && command[2] === 0x04 && command[3] === 0x00) { // Respond with success status (0x9000) const response = [0x90, 0x00]; await Nfc.respond({ data: response }); } // Check for custom command else if (command[0] === 0x00 && command[1] === 0x01) { // Respond with custom data const response = [0x48, 0x65, 0x6C, 0x6C, 0x6F, 0x90, 0x00]; // "Hello" + success status await Nfc.respond({ data: response }); } // Unknown command else { // Respond with error status (0x6D00 - Instruction not supported) const response = [0x6D, 0x00]; await Nfc.respond({ data: response }); } }); }; ``` ## API * [`startScanSession(...)`](#startscansession) * [`stopScanSession(...)`](#stopscansession) * [`write(...)`](#write) * [`respond(...)`](#respond) * [`makeReadOnly()`](#makereadonly) * [`erase()`](#erase) * [`format()`](#format) * [`transceive(...)`](#transceive) * [`connect(...)`](#connect) * [`close()`](#close) * [`isAvailable()`](#isavailable) * [`isSupported()`](#issupported) * [`isEnabled()`](#isenabled) * [`openSettings()`](#opensettings) * [`getAntennaInfo()`](#getantennainfo) * [`setAlertMessage(...)`](#setalertmessage) * [`checkPermissions()`](#checkpermissions) * [`requestPermissions()`](#requestpermissions) * [`addListener('commandReceived', ...)`](#addlistenercommandreceived-) * [`addListener('nfcLinkDeactivated', ...)`](#addlistenernfclinkdeactivated-) * [`addListener('nfcTagScanned', ...)`](#addlistenernfctagscanned-) * [`addListener('scanSessionCanceled', ...)`](#addlistenerscansessioncanceled-) * [`addListener('scanSessionError', ...)`](#addlistenerscansessionerror-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### startScanSession(...) ```typescript startScanSession(options?: StartScanSessionOptions | undefined) => Promise ``` 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(...) ```typescript stopScanSession(options?: StopScanSessionOptions | undefined) => Promise ``` Stop the active scan session. | Param | Type | | ------------- | ------------------------------------------------------------------------- | | **`options`** | StopScanSessionOptions | **Since:** 0.0.1 -------------------- ### write(...) ```typescript write(options: WriteOptions) => Promise ``` Write to a NFC tag. This method must be called from within a `nfcTagScanned` handler. | Param | Type | | ------------- | ----------------------------------------------------- | | **`options`** | WriteOptions | **Since:** 0.0.1 -------------------- ### respond(...) ```typescript respond(options: RespondOptions) => Promise ``` Send a response APDU back to the remote device. Only available on Android. | Param | Type | | ------------- | --------------------------------------------------------- | | **`options`** | RespondOptions | **Since:** 6.3.0 -------------------- ### makeReadOnly() ```typescript makeReadOnly() => Promise ``` 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() ```typescript erase() => Promise ``` 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() ```typescript format() => Promise ``` 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(...) ```typescript transceive(options: TransceiveOptions) => Promise ``` 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(...) ```typescript connect(options: ConnectOptions) => Promise ``` 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() ```typescript close() => Promise ``` Close the connection to the tag. This method must be called from within a `nfcTagScanned` handler. Only available on Android. **Since:** 6.0.0 -------------------- ### isAvailable() ```typescript isAvailable() => Promise ``` Returns whether or not NFC is available. **Returns:** Promise<IsAvailableResult> **Since:** 7.2.0 -------------------- ### isSupported() ```typescript isSupported() => Promise ``` Returns whether or not NFC is supported. **Returns:** Promise<IsSupportedResult> **Since:** 0.0.1 -------------------- ### isEnabled() ```typescript isEnabled() => Promise ``` Returns whether or not NFC is enabled. On **iOS** and **Web**, this method reflects whether NFC reading is available on the device. iOS does not expose a global NFC on/off setting. **Returns:** Promise<IsEnabledResult> **Since:** 0.0.1 -------------------- ### openSettings() ```typescript openSettings() => Promise ``` Opens the NFC device settings so that the user can enable or disable NFC. Only available on Android. **Since:** 0.0.1 -------------------- ### getAntennaInfo() ```typescript getAntennaInfo() => Promise ``` Returns information regarding Nfc antennas on the device such as their relative positioning on the device. Only available on Android. **Returns:** Promise<GetAntennaInfoResult> **Since:** 6.1.0 -------------------- ### setAlertMessage(...) ```typescript setAlertMessage(options: SetAlertMessageOptions) => Promise ``` Set a custom message, which is displayed in the NFC Reader Session alert. Only available on iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------- | | **`options`** | SetAlertMessageOptions | **Since:** 6.2.0 -------------------- ### checkPermissions() ```typescript checkPermissions() => Promise ``` 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() ```typescript requestPermissions() => Promise ``` 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('commandReceived', ...) ```typescript addListener(eventName: 'commandReceived', listenerFunc: (event: CommandReceivedEvent) => void) => Promise ``` Called whenever a NFC reader sends an Application Protocol Data Unit (APDU). Only available on Android. | Param | Type | | ------------------ | ----------------------------------------------------------------------------------------- | | **`eventName`** | 'commandReceived' | | **`listenerFunc`** | (event: CommandReceivedEvent) => void | **Returns:** Promise<PluginListenerHandle> **Since:** 6.3.0 -------------------- ### addListener('nfcLinkDeactivated', ...) ```typescript addListener(eventName: 'nfcLinkDeactivated', listenerFunc: (event: NfcLinkDeactivatedEvent) => void) => Promise ``` Called when the NFC link has been deactivated or lost. Only available on Android. | Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------- | | **`eventName`** | 'nfcLinkDeactivated' | | **`listenerFunc`** | (event: NfcLinkDeactivatedEvent) => void | **Returns:** Promise<PluginListenerHandle> **Since:** 6.3.0 -------------------- ### addListener('nfcTagScanned', ...) ```typescript addListener(eventName: 'nfcTagScanned', listenerFunc: (event: NfcTagScannedEvent) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'scanSessionCanceled', listenerFunc: () => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'scanSessionError', listenerFunc: (event: ScanSessionErrorEvent) => void) => Promise ``` 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() ```typescript removeAllListeners() => Promise ``` 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 | | **`compatibilityMode`** | boolean | Whether or not to use the [`NFCNDEFReaderSession`](https://developer.apple.com/documentation/corenfc/nfcndefreadersession). **Attention:** This mode only supports reading NDEF tags. Only available on iOS. | false | 6.4.0 | | **`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 | #### RespondOptions | Prop | Type | Description | Since | | ---------- | --------------------- | -------------- | ----- | | **`data`** | number[] | Bytes to send. | 6.3.0 | #### 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 and 0x24 are 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 | #### IsAvailableResult | Prop | Type | Description | Since | | --------- | -------------------- | -------------------------------------------------------------------- | ----- | | **`hce`** | boolean | Whether or not Host Card Emulation (HCE) is available on the device. | 7.2.0 | | **`nfc`** | boolean | Whether or not NFC is available on the device. | 7.2.0 | #### IsSupportedResult | Prop | Type | Description | Since | | ----------------- | -------------------- | -------------------------------------------------------------------- | ----- | | **`isSupported`** | boolean | | 0.0.1 | | **`nfc`** | boolean | Whether or not NFC is supported on the device. | 6.3.0 | | **`hce`** | boolean | Whether or not Host Card Emulation (HCE) is supported on the device. | 6.3.0 | #### IsEnabledResult | Prop | Type | Since | | --------------- | -------------------- | ----- | | **`isEnabled`** | boolean | 0.0.1 | #### GetAntennaInfoResult | Prop | Type | Description | Since | | ----------------------- | ---------------------- | ----------------------------------------- | ----- | | **`availableAntennas`** | Antenna[] | The available NFC antennas on the device. | 6.1.0 | | **`deviceHeight`** | number | The height of the device in millimeters. | 6.1.0 | | **`deviceWidth`** | number | The width of the device in millimeters. | 6.1.0 | | **`isDeviceFoldable`** | boolean | Whether or not the device is foldable. | 6.1.0 | #### Antenna | Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------------------------------- | ----- | | **`locationX`** | number | The location of the NFC antenna on the X axis in millimeters. | 6.1.0 | | **`locationY`** | number | The location of the NFC antenna on the Y axis in millimeters. | 6.1.0 | #### SetAlertMessageOptions | Prop | Type | Description | Since | | ------------- | ------------------- | ----------------------------------------------------------------------- | ----- | | **`message`** | string | The custom message, which is displayed in the NFC Reader Session alert. | 6.2.0 | #### PermissionResult | Prop | Type | Description | Since | | --------- | ----------------------------------------------------------- | -------------------------------------------------- | ----- | | **`nfc`** | PermissionState | Permission state for reading and writing NFC tags. | 0.0.1 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | #### CommandReceivedEvent | Prop | Type | Description | Since | | ---------- | --------------------- | -------------------------------------------- | ----- | | **`data`** | number[] | The command received from the remote device. | 6.3.0 | #### NfcLinkDeactivatedEvent | Prop | Type | Description | Since | | ------------ | ----------------------------------------------------------------- | ----------------------------------------- | ----- | | **`reason`** | DeactivationReason | The reason why the deactivation occurred. | 6.3.0 | #### 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 | | **`manufacturerCode`** | number | The Integrated Circuit (IC) manufacturer code of an NFC V tag. Only available on iOS. | 6.3.0 | | **`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 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' ### 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 | #### DeactivationReason | Members | Value | Description | Since | | ---------------- | -------------- | ----------------------------------------------------------------- | ----- | | **`LinkLoss`** | 0 | Indicates deactivation was due to the NFC link being lost. | 6.3.0 | | **`Deselected`** | 1 | Indicates deactivation was due to a different AID being selected. | 6.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 This plugin provides a utility class `NfcUtils` that can be used for various NFC-related operations, for example, creating NDEF records: ```ts import { NfcUtils } from '@capawesome-team/capacitor-nfc'; const createNdefTextRecord = () => { const utils = new NfcUtils(); const { record } = utils.createNdefTextRecord({ text: 'Capacitor NFC Plugin' }); return record; }; ``` See [docs/utils/README.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/docs/utils/README.md) for more information. ## Troubleshooting ##### `The connection to service named com.apple.nfcd.service.corenfc was invalidated from this process` This error occurs on iOS when the required NFC capability is not added to the app. To fix this, add the `Near Field Communication Tag Reading` capability in Xcode under the `Signing & Capabilities` tab. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information. ## FAQ ### What do I need to configure before using the plugin on iOS? You need to enable the `Near Field Communication Tag Reading` capability in Xcode, make sure the `App.entitlements` file contains the `com.apple.developer.nfc.readersession.formats` key, and add the `NFCReaderUsageDescription` key to the `Info.plist` file to tell the user why the app needs to use NFC. See the [Installation](#installation) section for details. If the capability is missing, the scan session fails with an error, as described in the [Troubleshooting](#troubleshooting) section. ### Is Host Card Emulation (HCE) available on all platforms? No, card emulation is only available on Android. The `respond(...)` method and the `commandReceived` event are Android-only, and you need to declare an HCE service in your `AndroidManifest.xml` as described in the [Installation](#installation) section. You can check whether HCE is supported on the device using the `isSupported()` method. ### Can I launch my app by scanning an NFC tag? Yes. On Android, you need to add an intent filter to your `AndroidManifest.xml` as described in the [Android documentation](https://developer.android.com/guide/topics/connectivity/nfc/nfc#dispatching). On iOS, the tag requires a URI record containing either a universal link or a supported URL scheme, as described in the [Core NFC documentation](https://developer.apple.com/documentation/corenfc/adding_support_for_background_tag_reading#3032598). See the [Installation](#installation) section for details. ### What is the difference between `isSupported` and `isEnabled`? The `isSupported()` method returns whether the device supports NFC and Host Card Emulation (HCE) at all, while the `isEnabled()` method returns whether NFC is currently enabled. On Android, you can open the NFC device settings with `openSettings()` so that the user can enable NFC. On iOS and Web, `isEnabled()` reflects whether NFC reading is available on the device, since iOS does not expose a global NFC on/off setting. ### Can making an NFC tag read-only be undone? No, the `makeReadOnly()` method permanently write-protects the tag and cannot be undone. On Android, you can check the `canMakeReadOnly` property of the scanned tag to find out whether it can be made read-only at all. ### Can I use this plugin with Ionic, React, Vue or Angular? Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins - [Bluetooth Low Energy](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/): Communicate with Bluetooth Low Energy (BLE) devices in the central and peripheral role. - [ML Kit Barcode Scanning](https://capawesome.io/docs/sdks/capacitor/mlkit/barcode-scanning/): Scan barcodes and QR codes with ML Kit Barcode Scanning. - [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information such as connection status and type, and listen for network changes. - [Wifi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/CHANGELOG.md). ## Breaking Changes See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/BREAKING.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nfc/LICENSE).