How epicshaggy/capacitor-native-biometric works
Major Components
• Frontend/JavaScript Layer – The plugin exposes its API via TypeScript/JavaScript in the “src” directory (files such as index.ts, web.ts, and definitions.ts). This is the entry point for app developers.
• Capacitor Bridge – The mechanism that connects the plugin’s JavaScript side with the native layers on iOS and Android.
• Android Native Component – Located under the “android” directory; it contains Java classes (such as NativeBiometric.java and AuthActivity.java), AndroidManifest, resource files, and tests. This component uses Android’s BiometricPrompt API and handles secure storage with the Keystore.
• iOS Native Component – Found in the “ios” directory, including an Xcode project, Plugin header/source files, and Swift files. This component interacts with iOS’s biometric frameworks (e.g., FaceID/TouchID) and performs secure storage using Keychain.
• Operating System Biometric Services – External services (on each platform) that actually execute the device’s biometric authentication.
• Secure Credential Store – Represents the storage system (iOS Keychain and Android Keystore) used to store/retrieve user credentials.
Out Relationships and Data Flow
• The application’s developer invokes a function (for example, verifyIdentity or setCredentials) via the JavaScript API.
• The invocation goes through the Capacitor Bridge which directs the request to the native platform’s plugin implementation.
• On Android, the request triggers biometric authentication (using classes like NativeBiometric and AuthActivity), which then communicates with Android’s biometric services through the native APIs.
• On iOS, similarly, the request invokes the native biometric methods defined in the Plugin folder to display biometric prompts and interact with FaceID/TouchID.
• After the biometric verification is complete, native modules interact with secure storage (Keychain/Keystore) to save or retrieve credentials securely.
• The response (success/failure, errors, or credentials) then flows back from the native modules through the Capacitor Bridge to the JavaScript API, which returns a Promise to the app’s code.
Architectural Patterns & Design Principles
• Bridge Pattern – The Capacitor Bridge acts as a mediator between the JS code and native implementations.
• Platform Abstraction – Unified API design so that the web-side developer does not worry about platform differences.
• Secure Storage and Authentication – Emphasis on security by using native secure storage and leveraging native biometric frameworks.
• Modular Design – Separation of concerns with independent modules (JS, Android, iOS) that interact through defined interfaces.
Following Elements
• “JavaScript API (src)”
• “Capacitor Bridge”
• “Android Plugin Module” with its key classes (e.g., NativeBiometric, AuthActivity)
• “iOS Plugin Module” (with Plugin.swift/Plugin.h implementations)
• “Native Biometric Services (Android API / iOS FaceID/TouchID)”
• “Secure Credential Store (Keystore / Keychain)”
• Data flow: e.g., API call from JS → Capacitor Bridge → Native Plugin
• Response flow: native verification result back up the chain.
• Dependency connections: native plugin’s dependency on OS services.
• “Credential Storage using Keychain (iOS)” and “Encryption via Keystore (Android)”
• “Biometric Prompt parameters and customization (see BiometricOptions in README)”
Final Advice
• Secure, modular, and cross-platform aspects of the plugin.