{"id":15018571,"url":"https://github.com/eddyverbruggen/nativescript-fingerprint-auth","last_synced_at":"2025-04-09T21:19:17.503Z","repository":{"id":33551699,"uuid":"37197894","full_name":"EddyVerbruggen/nativescript-fingerprint-auth","owner":"EddyVerbruggen","description":":nail_care: 👱‍♂️ Forget passwords, use a fingerprint scanner or facial recognition!","archived":false,"fork":false,"pushed_at":"2020-09-06T09:25:12.000Z","size":3812,"stargazers_count":133,"open_issues_count":24,"forks_count":33,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-09T21:19:11.011Z","etag":null,"topics":["faceid","fingerprint","fingerprint-scanner","nativescript","nativescript-plugin","passcode","touch-id","touchid"],"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}},"created_at":"2015-06-10T13:12:24.000Z","updated_at":"2025-02-05T02:31:06.000Z","dependencies_parsed_at":"2022-08-20T22:40:32.252Z","dependency_job_id":null,"html_url":"https://github.com/EddyVerbruggen/nativescript-fingerprint-auth","commit_stats":null,"previous_names":["eddyverbruggen/nativescript-touchid"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-fingerprint-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-fingerprint-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-fingerprint-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-fingerprint-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-fingerprint-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248111973,"owners_count":21049578,"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":["faceid","fingerprint","fingerprint-scanner","nativescript","nativescript-plugin","passcode","touch-id","touchid"],"created_at":"2024-09-24T19:52:07.897Z","updated_at":"2025-04-09T21:19:17.472Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NativeScript Fingerprint Authentication\n\n\u003e Also works with Face ID on iPhones 🚀\n\n[![Build Status][build-status]][build-url]\n[![NPM version][npm-image]][npm-url]\n[![Downloads][downloads-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[build-status]:https://travis-ci.org/EddyVerbruggen/nativescript-fingerprint-auth.svg?branch=master\n[build-url]:https://travis-ci.org/EddyVerbruggen/nativescript-fingerprint-auth\n[npm-image]:http://img.shields.io/npm/v/nativescript-fingerprint-auth.svg\n[npm-url]:https://npmjs.org/package/nativescript-fingerprint-auth\n[downloads-image]:http://img.shields.io/npm/dm/nativescript-fingerprint-auth.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\u003e ⚠️ Looking for NativeScript 7 compatibilty? Go to [the NativeScript/plugins repo](https://github.com/NativeScript/plugins/tree/master/packages/fingerprint-auth).\n\n\u003cimg src=\"https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/raw/master/media/fingerprint.png\" /\u003e\n\n## Installation\nFrom the command prompt go to your app's root folder and execute:\n```\ntns plugin add nativescript-fingerprint-auth\n```\n\nThen open `App_Resources/Android/AndroidManifest.xml` and look for `minSdkVersion`.\nIf that's set to a version less than 23, add this `overrideLibrary` line:\n\n```xml\n  \u003cuses-sdk\n      android:minSdkVersion=\"17\"\n      android:targetSdkVersion=\"__APILEVEL__\"\n      tools:overrideLibrary=\"com.jesusm.kfingerprintmanager\"/\u003e\n```\n\n## Demo\nIf you want a quickstart, [check out the demo app](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/tree/master/demo). Run it locally using these commands:\n\n```bash\ngit clone https://github.com/EddyVerbruggen/nativescript-fingerprint-auth\ncd nativescript-fingerprint-auth/src\nnpm run demo.android # or demo.ios\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-fingerprint-auth/master/media/ios-demo-01.png\" width=\"200px\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-fingerprint-auth/master/media/ios-demo-02.png\" width=\"200px\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-fingerprint-auth/master/media/ios-demo-03.png\" width=\"200px\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-fingerprint-auth/master/media/ios-demo-04.png\" width=\"200px\" /\u003e \u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-fingerprint-auth/master/media/ios-demo-05.png\" width=\"200px\" /\u003e\n\n## API\nWant a nicer guide than these raw code samples? Read [Nic Raboy's blog post about this plugin](https://www.thepolyglotdeveloper.com/2016/03/add-touch-id-authentication-support-to-your-nativescript-app/).\n\n### `available`\n\n#### JavaScript\n```js\nvar fingerprintAuthPlugin = require(\"nativescript-fingerprint-auth\");\nvar fingerprintAuth = new fingerprintAuthPlugin.FingerprintAuth();\n\nfingerprintAuth.available().then(\n    function(avail) {\n      console.log(\"Available? \" + avail);\n    }\n)\n```\n\n#### TypeScript\n\n```typescript\nimport { FingerprintAuth, BiometricIDAvailableResult } from \"nativescript-fingerprint-auth\";\n\nclass MyClass {\n  private fingerprintAuth: FingerprintAuth;\n\n  constructor() {\n    this.fingerprintAuth = new FingerprintAuth();\n  }\n\n  this.fingerprintAuth.available().then((result: BiometricIDAvailableResult) =\u003e {\n    console.log(`Biometric ID available? ${result.any}`);\n    console.log(`Touch? ${result.touch}`);\n    console.log(`Face? ${result.face}`);\n  });\n}\n```\n\n### `verifyFingerprint`\nNote that on the iOS simulator this will just `resolve()`.\n\n```typescript\nfingerprintAuth.verifyFingerprint(\n\t{\n\t  title: 'Android title', // optional title (used only on Android)\n\t  message: 'Scan yer finger', // optional (used on both platforms) - for FaceID on iOS see the notes about NSFaceIDUsageDescription\n\t  authenticationValidityDuration: 10, // optional (used on Android, default 5)\n\t  useCustomAndroidUI: false // set to true to use a different authentication screen (see below)\n\t})\n\t.then((enteredPassword?: string) =\u003e {\n\t  if (enteredPassword === undefined) {\n\t    console.log(\"Biometric ID OK\")\n\t  } else {\n\t    // compare enteredPassword to the one the user previously configured for your app (which is not the users system password!)\n\t  }\n\t})\n\t.catch(err =\u003e console.log(`Biometric ID NOT OK: ${JSON.stringify(err)}`));\n```\n\n#### A nicer UX/UI on Android (`useCustomAndroidUI: true`)\nThe default authentication screen on Android is a standalone screen that (depending on the exact Android version) looks kinda 'uninteresting'.\nSo with version 6.0.0 this plugin added the ability to override the default screen and offer an iOS popover style which you can activate by passing in `useCustomAndroidUI: true` in the function above.\n\nOne important thing to realize is that the 'use password' option in this dialog doesn't verify the entered password against\nthe system password. It must be used to compare the entered password with an app-specific password the user previously configured.\n\nThe password fallback can be disabled by overriding the default `use_password` text to a blank string (see optional change below for details on how to do this).\n\n##### Optional change\nIf you want to override the default texts of this popover screen, then drop a file [`strings.xml`](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/blob/5a14f96f7e752953df506401588b5694e3ab6444/demo/app/App_Resources/Android/src/main/res/values/strings.xml) in your project and override the properties you like. See the demo app for an example.\n\n##### ⚠️ Important note when using NativeScript \u003c 5.4.0\n**Use plugin version \u003c 7.0.0 to be able to use this feature with NativeScript \u003c 5.4.0**\n\n\u003e Skip this section if you're on NativeScript 5.4.0 or newer because it's all handled automatically! \n\nTo be able to use this screen, a change to `App_Resources/Android/AndroidManifest.xml` is required as our NativeScript activity needs to extend AppCompatActivity (note that in the future this may become the default for NativeScript apps).\n\nTo do so, open the file and replace `\u003cactivity android:name=\"com.tns.NativeScriptActivity\"` by `\u003cactivity android:name=\"org.nativescript.fingerprintplugin.AppCompatActivity\"`.\n\nNote that if you forget this and set `useCustomAndroidUI: true` the plugin will `reject` the Promise with a relevant error message.\n\n**Mandatory changes for webpack and snapshot builds (again, for NativeScript \u003c 5.4.0 only)**\n\nIf you are using Webpack with or without snapshot there are couple more changes required in order to make the custom UI work in your production builds.  \nFirst you need to edit your `vendor-platform.android.ts` file and add `require(\"nativescript-fingerprint-auth/appcompat-activity\");`. You can see the changed file in the demo app [here](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/blob/master/demo/app/vendor-platform.android.ts#L9).  \nThe second change should be made in your `webpack.config.js` file. Find the place where the `NativeScriptSnapshotPlugin` is pushed to the webpack plugins and add `\"nativescript-fingerprint-auth\"` in the `tnsJavaClassesOptions.packages` array. The result should look something like:\n```js\n// ...\n    if (snapshot) {\n        config.plugins.push(new nsWebpack.NativeScriptSnapshotPlugin({\n            chunk: \"vendor\",\n            projectRoot: __dirname,\n            webpackConfig: config,\n            targetArchs: [\"arm\", \"arm64\", \"ia32\"],\n            tnsJavaClassesOptions: {\n                packages: [\"tns-core-modules\", \"nativescript-fingerprint-auth\"],\n            },\n            useLibs: false\n        }));\n    }\n// ...\n```\n\n### `verifyFingerprintWithCustomFallback` (iOS only, falls back to `verifyFingerprint` on Android)\nInstead of falling back to the default Passcode UI of iOS you can roll your own.\nJust show that when the error callback is invoked.\n\n```typescript\nfingerprintAuth.verifyFingerprintWithCustomFallback({\n  message: 'Scan yer finger', // optional, shown in the fingerprint dialog (default: 'Scan your finger').\n  fallbackMessage: 'Enter PIN', // optional, the button label when scanning fails (default: 'Enter password').\n  authenticationValidityDuration: 10 // optional (used on Android, default 5)\n}).then(\n    () =\u003e {\n      console.log(\"Fingerprint was OK\");\n    },\n    error =\u003e {\n      // when error.code === -3, the user pressed the button labeled with your fallbackMessage\n      console.log(\"Fingerprint NOT OK. Error code: \" + error.code + \". Error message: \" + error.message);\n    }\n);\n```\n\n## Face ID (iOS)\niOS 11 added support for Face ID and was first supported by the iPhone X.\nThe developer needs to provide a value for `NSFaceIDUsageDescription`, otherwise your app may crash.\n\nYou can provide this value (the reason for using Face ID) by adding something like this to `app/App_Resources/ios/Info.plist`:\n\n```xml\n  \u003ckey\u003eNSFaceIDUsageDescription\u003c/key\u003e\n  \u003cstring\u003eFor easy authentication with our app.\u003c/string\u003e\n``` \n \n## Security++ (iOS)\nSince iOS9 it's possible to check whether or not the list of enrolled fingerprints changed since\nthe last time you checked it. It's recommended you add this check so you can counter hacker attacks\nto your app. See [this article](https://godpraksis.no/2016/03/fingerprint-trojan/) for more details.\n\nSo instead of checking the fingerprint after `available` add another check.\nIn case `didFingerprintDatabaseChange` returns `true` you probably want to re-authenticate your user\nbefore accepting valid fingerprints again.\n\n```typescript\nfingerprintAuth.available().then(avail =\u003e {\n    if (!avail) {\n      return;\n    }\n    fingerprintAuth.didFingerprintDatabaseChange().then(changed =\u003e {\n        if (changed) {\n          // re-auth the user by asking for his credentials before allowing a fingerprint scan again\n        } else {\n          // call the fingerprint scanner\n        }\n  });\n});\n```\n\n## Changelog\n- 6.2.0  [Fixed a potential bypass on iOS](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/issues/41).\n- 6.1.0  [Fixed potentioal bypasses on Android](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/milestone/8?closed=1).\n- 6.0.3  [Android interfered with other plugins' Intents](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/pull/28).\n- 6.0.2  [Plugin not working correctly on iOS production builds / TestFlight](https://github.com/EddyVerbruggen/nativescript-fingerprint-auth/issues/27).\n- 6.0.1  Fixed a compatibility issues with NativeScript 3.4.\n- 6.0.0  Allow custom UI on Android.\n- 5.0.0  Better `Face ID` support. Breaking change, see the API for `available`.\n- 4.0.1  Aligned with [the official NativeScript plugin seed](https://github.com/NativeScript/nativescript-plugin-seed). Requires NativeScript 3.0.0+. Thanks, @angeltsvetkov!\n- 4.0.0  Converted to TypeScript. Changed the error response type of `verifyFingerprintWithCustomFallback`.\n- 3.0.0  Android support added. Renamed `nativescript-touchid` to `nativescript-fingerprint-auth` (sorry for any inconvenience!).\n- 2.1.1  Xcode 8 compatibility - requires NativeScript 2.3.0+.\n- 2.1.0  Added `didFingerprintDatabaseChange` for enhanced security.\n- 2.0.0  Added `verifyFingerprintWithCustomFallback`, `verifyFingerprint` now falls back to the passcode.\n- 1.2.0  You can now use the built-in passcode interface as fallback.\n- 1.1.1  Added TypeScript definitions.\n- 1.1.0  Added Android platform which will always return false for `touchid.available`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-fingerprint-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-fingerprint-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-fingerprint-auth/lists"}