{"_id":"@day_time/capacitor-nfc-day","name":"@day_time/capacitor-nfc-day","dist-tags":{"latest":"0.0.10"},"versions":{"0.0.10":{"name":"@day_time/capacitor-nfc-day","version":"0.0.10","description":"A Capacitor plugin for reading and writing NFC NDEFtags.","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"DAYGood_Time"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/DAYGood_Time/capacitor-nfc-day.git"},"keywords":["capacitor","plugin","native"],"scripts":{"verify":"npm run verify:ios && npm run verify:android && npm run verify:web","verify:ios":"xcodebuild -scheme CapacitorNfc -destination generic/platform=iOS","verify:android":"cd android && ./gradlew clean build test && cd ..","verify:web":"npm run build","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","eslint":"eslint . --ext ts","prettier":"prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java","swiftlint":"node-swiftlint","docgen":"docgen --api NFCPlugin --output-readme README.md --output-json dist/docs.json","build":"npm run clean && tsc && rollup -c rollup.config.js && rimraf *.tgz && npm pack","clean":"rimraf ./dist","watch":"tsc --watch","prepublishOnly":"npm run build"},"devDependencies":{"@capacitor/android":"^6.0.0","@capacitor/core":"^6.0.0","@capacitor/docgen":"^0.2.2","@capacitor/ios":"^6.0.0","@ionic/eslint-config":"^0.4.0","@ionic/prettier-config":"^4.0.0","@ionic/swiftlint-config":"^1.1.2","eslint":"^8.57.0","prettier":"^3.3.3","prettier-plugin-java":"^2.6.4","rimraf":"^3.0.2","rollup":"^2.32.0","swiftlint":"^1.0.1","typescript":"~4.1.5"},"peerDependencies":{"@capacitor/core":">=6.0.0 <9.0.0"},"prettier":"@ionic/prettier-config","swiftlint":"@ionic/swiftlint-config","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"capacitor":{"ios":{"src":"ios","podspec":"ExxiliCapacitorNfc.podspec"},"android":{"src":"android"}},"_id":"@day_time/capacitor-nfc-day@0.0.10","gitHead":"264354fab98f76cbede3d78416d89e05d26e8cfc","bugs":{"url":"https://github.com/DAYGood_Time/capacitor-nfc-day/issues"},"homepage":"https://github.com/DAYGood_Time/capacitor-nfc-day#readme","_nodeVersion":"22.17.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-2ylk9wSxJ1/sS6+roMQdKJie1AWxbAJe8ktUFUbIs3G87R9c07oYfllNxzyO4CjXlkX7K4/X6IHZy+OywKNn/w==","shasum":"0fdcee93138c57ef43ece0f93ffbc6cefca90e0e","tarball":"https://registry.npmjs.org/@day_time/capacitor-nfc-day/-/capacitor-nfc-day-0.0.10.tgz","fileCount":25,"unpackedSize":98395,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA7T0NeiKMm/WFYgmvjOEU7JbuW2jwVrGITUrHOqkpqhAiAdlqWvJeFVWfeD5EuydYjFLL9Mh5/Fyma32llbowig6Q=="}]},"_npmUser":{"name":"day_time","email":"osutimemail@gmail.com"},"directories":{},"maintainers":[{"name":"day_time","email":"osutimemail@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-nfc-day_0.0.10_1756297101406_0.20290005483447415"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-27T12:18:21.322Z","0.0.10":"2025-08-27T12:18:21.674Z","modified":"2025-08-27T12:18:21.962Z"},"maintainers":[{"name":"day_time","email":"osutimemail@gmail.com"}],"description":"A Capacitor plugin for reading and writing NFC NDEFtags.","homepage":"https://github.com/DAYGood_Time/capacitor-nfc-day#readme","keywords":["capacitor","plugin","native"],"repository":{"type":"git","url":"git+https://github.com/DAYGood_Time/capacitor-nfc-day.git"},"author":{"name":"DAYGood_Time"},"bugs":{"url":"https://github.com/DAYGood_Time/capacitor-nfc-day/issues"},"license":"MIT","readme":"# Capacitor NFC Plugin (@exxili/capacitor-nfc)\r\n\r\nA Capacitor plugin for reading and writing NFC tags on iOS and Android devices. This plugin allows you to:\r\n\r\n- Read NDEF messages from NFC tags.\r\n- Write NDEF messages to NFC tags.\r\n\r\n**Note**: NFC functionality is only available on compatible iOS devices running iOS 13.0 or later.\r\n\r\n## Table of Contents\r\n\r\n- [Installation](#installation)\r\n- [iOS Setup](#ios-setup)\r\n- [Android Setup](#android-setup)\r\n- [Usage](#usage)\r\n  - [Reading NFC Tags](#reading-nfc-tags)\r\n  - [Writing NFC Tags](#writing-nfc-tags)\r\n- [API](#api)\r\n  - [Methods](#methods)\r\n    - [`isSupported()`](#issupported)\r\n    - [`startScan()`](#startscan)\r\n    - [`writeNDEF(options)`](#writendefoptions-ndefwriteoptionst-extends-string--number--uint8array--string)\r\n    - [`cancelWriteAndroid`](#cancelwriteandroid)\r\n  - [Listeners](#listeners)\r\n    - [`onRead(listener)`](#onreadlistener-data-ndefmessagestransformable--void)\r\n    - [`onError('listener)`](#onerrorlistener-error-nfcerror--void)\r\n    - [`onWrite(listener)`](#onwritelistener---void)\r\n  - [Interfaces](#interfaces)\r\n    - [`NDEFWriteOptions`](#ndefwriteoptions)\r\n    - [`NDEFWriteOptions`](#ndefmessagestransformable)\r\n    - [`NDEFMessages`](#ndefmessages)\r\n    - [`NDEFMessage`](#ndefmessage)\r\n    - [`NDEFRecord`](#ndefrecord)\r\n    - [`NFCError`](#nfcerror)\r\n- [Integration into a Capacitor App](#integration-into-a-capacitor-app)\r\n- [Example](#example)\r\n- [License](#license)\r\n\r\n## Installation\r\n\r\nInstall the plugin using npm:\r\n\r\n```bash\r\nnpm install @exxili/capacitor-nfc\r\nnpx cap sync\r\n```\r\n\r\n## iOS Setup\r\n\r\nTo use NFC functionality on iOS, you need to perform some additional setup steps.\r\n\r\n### 1. Enable NFC Capability\r\n\r\nIn Xcode:\r\n\r\n1. Open your project (`.xcworkspace` file) in Xcode.\r\n2. Select your project in the Project Navigator.\r\n3. Select your app target.\r\n4. Go to the **Signing & Capabilities** tab.\r\n5. Click the `+ Capability` button.\r\n6. Add **Near Field Communication Tag Reading**.\r\n\r\n### 2. Add Usage Description\r\n\r\nAdd the `NFCReaderUsageDescription` key to your `Info.plist` file to explain why your app needs access to NFC.\r\n\r\nIn your `Info.plist` file (usually located at `ios/App/App/Info.plist`), add:\r\n\r\n```xml\r\n<key>NFCReaderUsageDescription</key>\r\n<string>This app requires access to NFC to read and write NFC tags.</string>\r\n```\r\n\r\nReplace the description with a message that explains why your app needs NFC access.\r\n\r\n## Android Setup\r\n\r\nAdd the following to your `AndroidManifest.xml` file:\r\n\r\n```xml\r\n<uses-permission android:name=\"android.permission.NFC\" />\r\n<uses-feature android:name=\"android.hardware.nfc\" android:required=\"true\" />\r\n```\r\n\r\n## Usage\r\n\r\nImport the plugin into your code:\r\n\r\n```typescript\r\nimport { NFC } from '@exxili/capacitor-nfc';\r\n```\r\n\r\n### Reading NFC Tags\r\n\r\nTo read NFC tags, you need to listen for `nfcTag` events. On iOS, you must also start the NFC scanning session using `startScan()`.\r\n\r\n```typescript\r\nimport {NFC, NDEFMessagesTransformable, NFCError} from '@exxili/capacitor-nfc';\r\n\r\n// Start NFC scanning\r\nNFC.startScan().catch((error) => {\r\n  console.error('Error starting NFC scan:', error);\r\n});\r\n\r\n// Listen for NFC tag detection\r\nNFC.onRead((data: NDEFMessagesTransformable) => {\r\n  console.log('Received NFC tag:', data.string());\r\n});\r\n\r\n// Handle NFC errors\r\nNFC.onError('nfcError', (error: NFCError) => {\r\n  console.error('NFC Error:', error);\r\n});\r\n```\r\n\r\n### Writing NFC Tags\r\n\r\nTo write NDEF messages to NFC tags, use the `writeNDEF` method and listen for `onWrite` events.\r\n\r\n```typescript\r\nimport { NFC, NDEFWriteOptions, NFCError } from '@exxili/capacitor-nfc';\r\n\r\nconst message: NDEFWriteOptions = {\r\n  records: [\r\n    {\r\n      type: 'T', // Text record type\r\n      payload: 'Hello, NFC!',\r\n    },\r\n  ],\r\n};\r\n\r\n// Write NDEF message to NFC tag\r\nNFC.writeNDEF(message)\r\n  .then(() => {\r\n    console.log('Write initiated');\r\n  })\r\n  .catch((error) => {\r\n    console.error('Error writing to NFC tag:', error);\r\n  });\r\n\r\n// Listen for write success\r\nNFC.onWrite(() => {\r\n  console.log('NDEF message written successfully.');\r\n});\r\n\r\n// Handle NFC errors\r\nNFC.onError((error: NFCError) => {\r\n  console.error('NFC Error:', error);\r\n});\r\n```\r\n\r\n## API\r\n\r\n### Methods\r\n\r\n#### `isSupported()`\r\n\r\nReturns if NFC is supported on the scanning device.\r\n\r\n**Returns**: `Promise<{ supported: boolean }>`\r\n\r\n#### `startScan()`\r\n\r\nStarts the NFC scanning session on ***iOS only***. Android devices are always in reading mode, so setting up the `nfcTag` listener is sufficient to handle tag reads on Android.\r\n\r\n**Returns**: `Promise<void>`\r\n\r\n```typescript\r\nNFC.startScan()\r\n  .then(() => {\r\n    // Scanning started\r\n  })\r\n  .catch((error) => {\r\n    console.error('Error starting NFC scan:', error);\r\n  });\r\n```\r\n\r\n#### `writeNDEF(options: NDEFWriteOptions<T extends string | number[] | Uint8Array = string)`\r\n\r\nWrites an NDEF message to an NFC tag.\r\n\r\nPayload may be provided as a string, `Uint8Array`, or an array of numbers. The plugin will automatically convert the payload to a byte array for storage on the NFC tag.\r\n\r\nAndroid use: since Android has no default UI for reading and writing NFC tags, it is recommended that you add a UI indicator to your application when calling `writeNDEF` and remove it in the `nfcWriteSuccess` listener callback and the `nfcError` listener callback. This will prevent accidental writes to tags that your users intended to read from.\r\n\r\n**Parameters**:\r\n\r\n- `options: NDEFWriteOptions<T extends string | number[] | Uint8Array = string>` - The NDEF message to write.\r\n\r\n**Returns**: `Promise<void>`\r\n\r\n```typescript\r\nNFC.writeNDEF(options)\r\n  .then(() => {\r\n    // Write initiated\r\n  })\r\n  .catch((error) => {\r\n    console.error('Error writing NDEF message:', error);\r\n  });\r\n```\r\n\r\n#### `cancelWriteAndroid()`\r\n\r\nCancels an Android NFC write operation. Android does not have a native UI for NFC tag writing, so this method allows developers to hook up a custom UI to cancel an in-progress scan.\r\n\r\n### Listeners\r\n\r\n#### `onRead(listener: (data: NDEFMessagesTransformable) => void)`\r\n\r\nAdds a listener for NFC tag detection events. Returns type `NDEFMessagesTransformable`, which returns the following methods to provide the payload:\r\n\r\n* `string()`: Returns `NDEFMessages<string>`, where all payloads are strings.\r\n* `base64()`: Returns `NDEFMessages<string>`, where all payloads are the base64-encoded payloads read from the NFC tag.\r\n* `uint8Array()`: Returns `NDEFMessages<Uint8Array>`, where all payloads are the `Uint8Array` bytes from the NFC tag.\r\n* `numberArray()`: Returns `NDEFMessages<number[]>`, where all payloads bytes from the NFC tag represented as a `number[]`.\r\n\r\n**Parameters**:\r\n\r\n- `listener: (data: NDEFMessagesTransformable) => void` - The function to call when an NFC tag is detected.\r\n\r\n**Returns**: `void`\r\n\r\n```typescript\r\nNFC.onRead((data: NDEFMessages) => {\r\n  console.log('Received NFC tag:', data);\r\n});\r\n```\r\n\r\n#### `onError(listener: (error: NFCError) => void)`\r\n\r\nAdds a listener for NFC error events.\r\n\r\n**Parameters**:\r\n\r\n- `listener: (error: NFCError) => void` - The function to call when an NFC error occurs.\r\n\r\n**Returns**: `PluginListenerHandle`\r\n\r\n```typescript\r\nNFC.onError((error: NFCError) => {\r\n  console.error('NFC Error:', error);\r\n});\r\n```\r\n\r\n#### `onWrite(listener: () => void)`\r\n\r\nAdds a listener for NFC write success events.\r\n\r\n**Parameters**:\r\n\r\n- `listener: () => void` - The function to call when an NDEF message has been written successfully.\r\n\r\n**Returns**: `PluginListenerHandle`\r\n\r\n```typescript\r\nNFC.onWrite('nfcWriteSuccess', () => {\r\n  console.log('NDEF message written successfully.');\r\n});\r\n```\r\n\r\n### Interfaces\r\n\r\n#### `NDEFWriteOptions`\r\n\r\nOptions for writing an NDEF message.\r\n\r\n```typescript\r\ninterface NDEFWriteOptions<T extends string | number[] | Uint8Array = string> {\r\n  records: NDEFRecord<T>[];\r\n}\r\n```\r\n\r\n#### `NDEFMessagesTransformable`\r\n\r\nReturned by `onRead` and includes the following methods to provide the payload:\r\n\r\n* `string()`: Returns `NDEFMessages<string>`, where all payloads are strings.\r\n* `base64()`: Returns `NDEFMessages<string>`, where all payloads are the base64-encoded payloads read from the NFC tag.\r\n* `uint8Array()`: Returns `NDEFMessages<Uint8Array>`, where all payloads are the `Uint8Array` bytes from the NFC tag.\r\n* `numberArray()`: Returns `NDEFMessages<number[]>`, where all payloads bytes from the NFC tag represented as a `number[]`.\r\n\r\n```typescript\r\ninterface NDEFMessagesTransformable {\r\n  base64: ()=> NDEFMessages;\r\n  uint8Array: ()=> NDEFMessages<Uint8Array>;\r\n  string: ()=> NDEFMessages;\r\n  numberArray: ()=> NDEFMessages<number[]>;\r\n}\r\n```\r\n\r\n#### `NDEFMessages`\r\n\r\nData received from an NFC tag.\r\n\r\n```typescript\r\ninterface NDEFMessages {\r\n  messages: NDEFMessage[];\r\n}\r\n```\r\n\r\n#### `NDEFMessage`\r\n\r\nAn NDEF message consisting of one or more records.\r\n\r\n```typescript\r\ninterface NDEFMessage {\r\n  records: NDEFRecord[];\r\n}\r\n```\r\n\r\n#### `NDEFRecord`\r\n\r\nAn NDEF record. `payload` is, by default, an array of bytes representing the data; this is how an `NDEFRecord` is read from an NFC tag. You can choose to provide an `NDEFRecord` as a string a `Uint8Array` also.\r\n\r\n```typescript\r\ninterface NDEFRecord<T = number[]> {\r\n  /**\r\n   * The type of the record.\r\n   */\r\n  type: string;\r\n\r\n  /**\r\n   * The payload of the record.\r\n   */\r\n  payload: T;\r\n}\r\n````\r\n\r\n#### `NFCError`\r\n\r\nAn NFC error.\r\n\r\n```typescript\r\ninterface NFCError {\r\n  /**\r\n   * The error message.\r\n   */\r\n  error: string;\r\n}\r\n```\r\n\r\n## Integration into a Capacitor App\r\n\r\nTo integrate this plugin into your Capacitor app:\r\n\r\n1. **Install the plugin:**\r\n\r\n   ```bash\r\n   npm install @exxili/capacitor-nfc\r\n   npx cap sync\r\n   ```\r\n\r\n2. **Import the plugin in your code:**\r\n\r\n   ```typescript\r\n   import { NFC } from '@exxili/capacitor-nfc';\r\n   ```\r\n\r\n3. **Use the plugin methods as described in the [Usage](#usage) section.**\r\n\r\n## Example\r\n\r\nHere's a complete example of how to read and write NFC tags in your app:\r\n\r\n```typescript\r\nimport { NFC, NDEFMessages, NDEFWriteOptions, NFCError } from '@exxili/capacitor-nfc';\r\n\r\n// Check if NFC is supported\r\nconst { supported } = await NFC.isSupported();\r\n\r\n// Start NFC scanning -- iOS only\r\nNFC.startScan().catch((error) => {\r\n  console.error('Error starting NFC scan:', error);\r\n});\r\n\r\n// Listen for NFC tag detection\r\nNFC.onRead((data: NDEFMessages) => {\r\n  const stringMessages: NDEFMessage<string> = data.string();\r\n  const uint8ArrayMessages: NDEFMessage<Uint8Array> = data.uint8Array();\r\n  \r\n  // Print all Uint8Array payloads\r\n  console.log('Received NFC tag:', stringMessages.messages?.at(0)?.records?.at(0).payload);    // prints string[]\r\n  console.log('Received NFC tag:', uint8ArrayPayloads.messages?.at(0)?.records?.at(0).payload);    // prints Uint8Array[]\r\n});\r\n\r\n// Handle NFC errors\r\nNFC.onError((error: NFCError) => {\r\n  console.error('NFC Error:', error);\r\n});\r\n\r\n// Prepare an NDEF message to write\r\nconst message: NDEFWriteOptions = {\r\n  records: [\r\n    {\r\n      type: 'T', // Text record type\r\n      payload: 'Hello, NFC!',\r\n    },\r\n  ],\r\n};\r\n\r\n// Write NDEF message to NFC tag\r\nNFC.writeNDEF(message)\r\n  .then(() => {\r\n    console.log('Write initiated');\r\n  })\r\n  .catch((error) => {\r\n    console.error('Error writing to NFC tag:', error);\r\n  });\r\n\r\n// Listen for write success\r\nNFC.onWrite('nfcWriteSuccess', () => {\r\n  console.log('NDEF message written successfully.');\r\n});\r\n```\r\n\r\n## License\r\n\r\n[MIT License](https://opensource.org/license/mit)\r\n\r\n---\r\n\r\n**Support**: If you encounter any issues or have questions, feel free to open an issue.\r\n\r\n---\r\n","readmeFilename":"README.md","_rev":"1-cc65908e5438b0173b5f468ffab8e2ba"}