Skip to content
Capgo

Getting Started

  1. Install the package

    Terminal window
    npm i @capgo/capacitor-native-biometric

  2. Sync with native projects

    Terminal window
    npx cap sync

  3. Configure permissions

    iOS

    Add Face ID usage description to your Info.plist:

    <key>NSFaceIDUsageDescription</key>
    <string>For secure authentication</string>

    Android

    Add biometric permission to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.USE_BIOMETRIC" />

Usage

Import the plugin and use its methods for biometric authentication:

import { NativeBiometric } from '@capgo/capacitor-native-biometric';


// Check if biometric authentication is available
const checkBiometric = async () => {
  const result = await NativeBiometric.isAvailable();


  if (result.isAvailable) {
    console.log(`Biometric type: ${result.biometryType}`);
  }
};


// Perform biometric verification
const verify = async () => {
  const verified = await NativeBiometric.verifyIdentity({
    reason: "For secure access to your account",
    title: "Authentication",
    subtitle: "Verify your identity",
    description: "Place your finger on the sensor"
  })
    .then(() => true)
    .catch(() => false);


  if (verified) {
    console.log("Authentication successful");
  }
};


// Store credentials securely
const saveCredentials = async () => {
  await NativeBiometric.setCredentials({
    username: "user@example.com",
    password: "securepassword",
    server: "https://api.example.com"
  });
};


// Retrieve stored credentials
const getCredentials = async () => {
  const credentials = await NativeBiometric.getCredentials({
    server: "https://api.example.com"
  });


  console.log(credentials.username);
  console.log(credentials.password);
};


// Delete stored credentials
const deleteCredentials = async () => {
  await NativeBiometric.deleteCredentials({
    server: "https://api.example.com"
  });
};

API Reference

isAvailable()

Checks if biometric authentication is available on the device.

interface AvailableResult {
  isAvailable: boolean;
  biometryType?: BiometryType;
  errorCode?: number;
}


enum BiometryType {
  NONE = 0,
  TOUCH_ID = 1,
  FACE_ID = 2,
  FINGERPRINT = 3,
  FACE_AUTHENTICATION = 4,
  IRIS_AUTHENTICATION = 5
}

verifyIdentity(options)

Performs biometric authentication.

interface BiometricOptions {
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  fallbackTitle?: string;
  useFallback?: boolean;
  maxAttempts?: number;
}

setCredentials(options)

Stores credentials securely with biometric protection.

interface Credentials {
  username: string;
  password: string;
  server: string;
}

getCredentials(options)

Retrieves stored credentials after biometric authentication.

interface GetCredentialOptions {
  server: string;
}

deleteCredentials(options)

Deletes stored credentials.

interface DeleteCredentialOptions {
  server: string;
}

Best Practices

  1. Always check availability first

    const result = await NativeBiometric.isAvailable();
    if (!result.isAvailable) {
      // Fall back to password authentication
    }

  2. Provide clear reasons Always explain why you need biometric authentication to build user trust.

  3. Handle errors gracefully

    try {
      await NativeBiometric.verifyIdentity({
        reason: "Access your secure data"
      });
    } catch (error) {
      // Handle cancellation or failure
      console.log("Authentication failed or cancelled");
    }

  4. Use appropriate fallbacks Enable passcode fallback for devices where biometrics may fail.

Platform Differences

iOS

  • Supports Touch ID and Face ID
  • Requires NSFaceIDUsageDescription for Face ID
  • Fallback to device passcode available

Android

  • Supports fingerprint, face, and iris recognition
  • Requires USE_BIOMETRIC permission
  • Biometric Prompt API for Android 9+