BiometricNativePlugin

BiometricNativePlugin provides secure, key-value storage using the device's biometric authentication (e.g., Face ID, Touch ID, or Fingerprint). It is designed for hybrid mobile applications (Ionic/Cordova/Capacitor) needing secure, user-verified access to sensitive data.

Table of Contents

• Interface
• Methods
  • getItem
  • setItem
  • removeItem
• Platform-Specific Behavior
• Usage Examples
• Error Handling
• Notes

Interface

export interface BiometricNativePlugin {
  getItem(options: { key: string }): Promise<{ value: string; error?: any; }>;
  setItem(options: { key: string; value: string }): Promise<{ error?: any }>;
  removeItem(options: { key: string }): Promise<{ error?: any }>;
}

Methods

getItem

Description:
Asynchronously retrieves a value from secure storage. Biometric authentication is always required.

Parameters:

• options.key (string, required): The key to be retrieved.

Returns:
A Promise resolving to:

{
  value: string;    // The retrieved value (if found)
  error?: any;      // Error, in case retrieval or authentication fails
}

setItem

Description:
Asynchronously stores a value into secure storage.

• On Android: Will always require biometric authentication.
• On iOS: Biometric authentication is required only if overwriting an existing key.

Parameters:

• options.key (string, required): Key to store or update.
• options.value (string, required): Value to associate with the key.

Returns:
A Promise resolving to:

{
  error?: any; // Error, if storage or authentication fails
}

removeItem

Description:
Asynchronously removes a key from secure storage.

Biometric authentication is never invoked on either platform.

Parameters:

• options.key (string, required): Key to remove.

Returns:
A Promise resolving to:

{
  error?: any; // Error, if removal fails
}

Platform-Specific Behavior

| Method | Android – Biometric Required | iOS – Biometric Required | |--------------|:---------------------------:|:-------------------------------:| | getItem | ✔️ Always | ✔️ Always | | setItem | ✔️ Always | ✔️ Only if overwriting a key | | removeItem | ❌ Never | ❌ Never |

Usage Examples

// Retrieve a secure value (will prompt for biometrics)
const result = await BiometricNativePlugin.getItem({ key: 'mySecretKey' });

// Save a secure value (will prompt for biometrics per platform rules)
await BiometricNativePlugin.setItem({ key: 'mySecretKey', value: 'topSecret' });

// Remove a secure value (will NOT prompt for biometrics)
await BiometricNativePlugin.removeItem({ key: 'mySecretKey' });

Error Handling

All methods return an error object if an operation fails, including biometric authentication failures.
Always handle errors in your implementation to ensure a robust user experience.

Notes

• This plugin is suitable for use with hybrid mobile frameworks such as Ionic, Capacitor, or Cordova.
• For more information about biometric APIs, refer to the Android and Apple official documentation.