{"id":15141920,"url":"https://github.com/eddyverbruggen/nativescript-nfc","last_synced_at":"2025-04-13T09:43:07.895Z","repository":{"id":41287894,"uuid":"73004592","full_name":"EddyVerbruggen/nativescript-nfc","owner":"EddyVerbruggen","description":":pencil: NativeScript plugin to discover, read, and write NFC tags","archived":false,"fork":false,"pushed_at":"2023-04-06T12:31:43.000Z","size":3458,"stargazers_count":85,"open_issues_count":25,"forks_count":37,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-24T09:21:19.959Z","etag":null,"topics":["nativescript","nativescript-plugin","ndef","nfc","nfc-tag","rfid"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EddyVerbruggen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-06T16:45:53.000Z","updated_at":"2024-10-02T11:45:28.000Z","dependencies_parsed_at":"2024-06-20T23:30:47.941Z","dependency_job_id":"6ce7202f-7e34-4c8b-a413-9d5f639fc4f1","html_url":"https://github.com/EddyVerbruggen/nativescript-nfc","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-nfc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-nfc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-nfc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-nfc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-nfc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248693906,"owners_count":21146885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nativescript","nativescript-plugin","ndef","nfc","nfc-tag","rfid"],"created_at":"2024-09-26T09:20:33.707Z","updated_at":"2025-04-13T09:43:07.876Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NativeScript NFC plugin\n\n[![NPM version][npm-image]][npm-url]\n[![Downloads][downloads-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[npm-image]: http://img.shields.io/npm/v/nativescript-nfc.svg\n[npm-url]: https://npmjs.org/package/nativescript-nfc\n[downloads-image]: http://img.shields.io/npm/dm/nativescript-nfc.svg\n[twitter-image]: https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social\u0026label=Follow%20me\n[twitter-url]: https://twitter.com/eddyverbruggen\n\n\u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-nfc/master/screenshots/ios-demo-before-scan.PNG\" width=\"180px\" height=\"320px\"/\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-nfc/master/screenshots/ios-demo-after-scan.PNG\" width=\"180px\" height=\"320px\"/\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-nfc/master/screenshots/android-demo.png\" width=\"180px\" height=\"320px\"/\u003e\n\n## Installation\n\nFrom the command prompt go to your app's root folder and execute:\n\n### NativeScript Version 7+:\n\n```bash\nns plugin add nativescript-nfc\n```\n\n### NativeScript Version 6 and below:\n\n```bash\ntns plugin add nativescript-nfc@4.1.0\n```\n\n## iOS Setup\n\niOS requires you to enable 'NFC Tag Reading' for your App ID [here](https://developer.apple.com/account/ios/identifier/bundle).\n\nAlso, add this to your `App_Resources/iOS/app.entitlements` (mind the name!) file:\n\n```xml\n\u003ckey\u003ecom.apple.developer.nfc.readersession.formats\u003c/key\u003e\n\u003carray\u003e\n\t\u003cstring\u003eNDEF\u003c/string\u003e\n\u003c/array\u003e\n```\n\nThe [demo app](demo) has this:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n\t\u003ckey\u003ecom.apple.developer.nfc.readersession.formats\u003c/key\u003e\n\t\u003carray\u003e\n\t\t\u003cstring\u003eNDEF\u003c/string\u003e\n\t\u003c/array\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n## Android Setup\n\n\u003e ⚠️ Since plugin version 4.0.0 this section is no longer needed, but you'll HAVE to run NativeScript 5.4.0 or newer. If you're using an older NativeScript, please stick to a plugin version \u003c 4.0.0.\n\nUpdate the `activity` entry in your `App_Resources/Android/AndroidManifest.xml` file:\n\n```xml\n\u003cactivity\n        android:name=\"com.tns.NativeScriptNfcActivity\"\n        android:label=\"@string/title_activity_kimera\"\n        android:configChanges=\"keyboardHidden|orientation|screenSize\"\u003e\n```\n\nSo replace `com.tns.NativeScriptActivity` with `com.tns.NativeScriptNfcActivity`.\n\n#### Webpack (again, no longer needed from plugin version 4.0.0)\n\nIf you're using Webpack to bundle your app you'll need to add 1 line of configuration in case you're targeting Android.\n\n- Open `webpack.config.js` (it's in the root of your project).\n- Look for an Array named `appComponents`, which likely contains stuff like `\"tns-core-modules/ui/frame\"`.\n- Add `resolve(__dirname, \"node_modules/nativescript-nfc/nfc-activity.android.js\")` [as shown here](https://github.com/EddyVerbruggen/nativescript-nfc/blob/6dfa0ff4f77cab5ab7f494ac3055f728ce51d131/demo/webpack.config.js#L17).\n\n## Demo app (those screenshots above)\n\nWant to dive in quickly? Check out [the demo](https://github.com/EddyVerbruggen/nativescript-nfc/tree/master/demo)!\n\nYou can run the demo app from the root of the project by typing `npm run demo.ios.device` or `npm run demo.android`.\n\n\u003e [This is what it looks like in action on iOS](https://twitter.com/eddyverbruggen/status/899617497741185025)!\n\n## API\n\n### `available`\n\nNot all devices have an NFC chip we can tap in to (and on iOS you need to build with Xcode 9+), so check this beforehand:\n\n##### JavaScript\n\n```js\n// require the plugin\nvar Nfc = require(\"nativescript-nfc\").Nfc;\n\n// instantiate the plugin\nvar nfc = new Nfc();\n\nnfc.available().then(function (avail) {\n  console.log(avail ? \"Yes\" : \"No\");\n});\n```\n\n##### TypeScript\n\n```typescript\n// require the plugin\nimport { Nfc } from \"nativescript-nfc\";\n\n// instantiate the plugin\nlet nfc = new Nfc();\n\nnfc.available().then(avail =\u003e {\n  console.log(avail ? \"Yes\" : \"No\");\n});\n```\n\n### `enabled`\n\nA device may have an NFC chip, but it needs to be turned on ✅ in order to be available for this plugin. So if `available` returns `true` and `enabled` returns `false` you should prompt the user to turn NFC on in the device settings.\n\n##### JavaScript\n\n```js\nnfc.enabled().then(function (on) {\n  console.log(on ? \"Yes\" : \"No\");\n});\n```\n\n##### TypeScript\n\n```typescript\nnfc.enabled().then(on =\u003e {\n  console.log(on ? \"Yes\" : \"No\");\n});\n```\n\n### `setOnNdefDiscoveredListener`\n\nYou may want to get notified when an Ndef tag was discovered. You can pass in a callback function that gets invoked when that is the case.\n\nNote that blank/erased NFC tags are not returned here, but through `setOnTagDiscoveredListener` instead.\n\nSee the [definition of NfcNdefData](https://github.com/EddyVerbruggen/nativescript-nfc/blob/master/nfc.common.d.ts#L27-L33) to learn what is returned to the callback function.\n\nFor iOS you can pass in these options (see the TypeScript example below):\n\n- `stopAfterFirstRead: boolean` (default `false`): don't continue scanning after a tag was read.\n- `scanHint: string` (default `undefined`): Show a little hint in the scan UI.\n\n##### JavaScript\n\n```js\nnfc\n  .setOnNdefDiscoveredListener(function (data) {\n    // see the TypeScript example below\n  })\n  .then(function () {\n    console.log(\"OnNdefDiscovered listener added\");\n  });\n```\n\n##### TypeScript\n\n```typescript\nimport { NfcNdefData } from \"nativescript-nfc\";\n\nnfc\n  .setOnNdefDiscoveredListener(\n    (data: NfcNdefData) =\u003e {\n      // data.message is an array of records, so:\n      if (data.message) {\n        for (let m in data.message) {\n          let record = data.message[m];\n          console.log(\n            \"Ndef discovered! Message record: \" + record.payloadAsString\n          );\n        }\n      }\n    },\n    {\n      // iOS-specific options\n      stopAfterFirstRead: true,\n      scanHint: \"Scan a tag, baby!\"\n    }\n  )\n  .then(() =\u003e {\n    console.log(\"OnNdefDiscovered listener added\");\n  });\n```\n\nYou can pass in `null` instead of a callback function if you want to remove the listener.\n\n##### TypeScript\n\n```typescript\nnfc.setOnNdefDiscoveredListener(null).then(() =\u003e {\n  console.log(\"OnNdefDiscovered listener removed\");\n});\n```\n\n### `setOnTagDiscoveredListener` (Android only)\n\nYou may want to get notified when an NFC tag was discovered.\nYou can pass in a callback function that gets invoked when that is the case.\n\nNote that Ndef tags (which you may have previously written data to) are not returned here,\nbut through `setOnNdefDiscoveredListener` instead.\n\nSee the [definition of NfcTagData](https://github.com/EddyVerbruggen/nativescript-nfc/blob/master/nfc.common.d.ts#L14-L17) to learn what is returned to the callback function.\n\n##### JavaScript\n\n```js\nnfc\n  .setOnTagDiscoveredListener(function (data) {\n    console.log(\"Discovered a tag with ID \" + data.id);\n  })\n  .then(function () {\n    console.log(\"OnTagDiscovered listener added\");\n  });\n```\n\n##### TypeScript\n\n```typescript\nimport { NfcTagData } from \"nativescript-nfc\";\n\nnfc\n  .setOnTagDiscoveredListener((data: NfcTagData) =\u003e {\n    console.log(\"Discovered a tag with ID \" + data.id);\n  })\n  .then(() =\u003e {\n    console.log(\"OnTagDiscovered listener added\");\n  });\n```\n\nYou can pass in `null` instead of a callback function if you want to remove the listener.\n\n##### TypeScript\n\n```typescript\nnfc.setOnTagDiscoveredListener(null).then(() =\u003e {\n  console.log(\"OnTagDiscovered listener removed\");\n});\n```\n\n### `writeTag` (Android only)\n\nYou can write to a tag as well with this plugin. At the moment you can write either plain text or a Uri. The latter will launch the browser on an Android device if the tag is scanned (unless an app handling Ndef tags itself is active at that moment, like an app with this plugin - so just close the app to test this feature).\n\nNote that you can write multiple items to an NFC tag so the input is an object with Arrays of various types (`textRecord` and `uriRecord` are currently supported). See the [TypeScript definition](https://github.com/EddyVerbruggen/nativescript-nfc/blob/master/nfc.common.d.ts#L10-L13) for details, but these examples should get you going:\n\n##### Writing 2 textRecords in JavaScript\n\n```js\nnfc\n  .writeTag({\n    textRecords: [\n      {\n        id: [1],\n        text: \"Hello\"\n      },\n      {\n        id: [3, 7],\n        text: \"Goodbye\"\n      }\n    ]\n  })\n  .then(\n    function () {\n      console.log(\"Wrote text records 'Hello' and 'Goodbye'\");\n    },\n    function (err) {\n      alert(err);\n    }\n  );\n```\n\n##### Writing a uriRecord in TypeScript\n\n```typescript\nnfc\n  .writeTag({\n    uriRecords: [\n      {\n        id: [100],\n        uri: \"https://www.progress.com\"\n      }\n    ]\n  })\n  .then(\n    () =\u003e {\n      console.log(\"Wrote Uri record 'https://www.progress.com\");\n    },\n    err =\u003e {\n      alert(err);\n    }\n  );\n```\n\n### `eraseTag` (Android only)\n\nAnd finally, you can erase all content from a tag if you like.\n\n##### JavaScript\n\n```js\nnfc.eraseTag().then(function () {\n  console.log(\"Tag erased\");\n});\n```\n\n##### TypeScript\n\n```typescript\nnfc.eraseTag().then(() =\u003e {\n  console.log(\"Tag erased\");\n});\n```\n\n## Tips\n\n### Writing to an empty tag\n\nYou first need to \"discover\" it with `setOnTagDiscoveredListener` (see below). While you're still \"near\" the tag you can call `writeTag`.\n\n### Writing to a non-empty tag\n\nSame as above, but discovery is done through `setOnNdefDiscoveredListener`.\n\n## Future work\n\n- Peer to peer communication between two NFC-enabled devices.\n- Support for writing other types in addition to 'text' and 'uri'.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-nfc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-nfc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-nfc/lists"}