Skip to content
Capgo - Live Updates for Capacitor Apps 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

    Section titled “iOS”

    Add Face ID usage description to your Info.plist:

    <key>NSFaceIDUsageDescription</key>
    <string>Authenticate securely to access your account</string>

    Android

    Section titled “Android”

    Add biometric permission to your AndroidManifest.xml:

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

  4. Check availability before prompting Always inspect full availability details before showing authentication UIs.

Usage

Section titled “Usage”

Import the plugin and use its methods for biometric authentication:

import {
  NativeBiometric,
  BiometryType,
  AuthenticationStrength,
  AccessControl,
} from '@capgo/capacitor-native-biometric';


const checkBiometric = async () => {
  const result = await NativeBiometric.isAvailable({ useFallback: true });
  console.log('Biometric available:', result.isAvailable);
  console.log('Strength:', result.authenticationStrength); // STRONG | WEAK | NONE
  console.log('Primary type:', result.biometryType);
  console.log('Device is secure:', result.deviceIsSecure);
  console.log('Strong biometry:', result.strongBiometryIsAvailable);
};


const verify = async () => {
  await NativeBiometric.verifyIdentity({
    reason: 'Open secure section',
    title: 'Biometric Login',
    subtitle: 'Unlock with face, fingerprint, or credentials',
    description: 'Authenticate to continue',
    negativeButtonText: 'Cancel',
    maxAttempts: 5,
    allowedBiometryTypes: [BiometryType.FINGERPRINT, BiometryType.FACE_ID],
  });
};


const saveCredentials = async () => {
  await NativeBiometric.setCredentials({
    username: 'user@example.com',
    password: 'securepassword',
    server: 'https://api.example.com',
    accessControl: AccessControl.BIOMETRY_ANY,
  });
};


const getCredentials = async () => {
  const credentials = await NativeBiometric.getSecureCredentials({
    server: 'https://api.example.com',
    reason: 'Sign in again',
    title: 'Confirm identity',
  });
  console.log(credentials.username);
};


const alreadySaved = async () => {
  const { isSaved } = await NativeBiometric.isCredentialsSaved({
    server: 'https://api.example.com',
  });
  console.log('Credentials saved:', isSaved);
};


const cleanup = async () => {
  await NativeBiometric.deleteCredentials({
    server: 'https://api.example.com',
  });
};


const watchChanges = async () => {
  const handle = await NativeBiometric.addListener('biometryChange', (result) => {
    console.log('Biometry availability changed:', result.isAvailable);
    console.log('Type:', result.biometryType);
  });


  // Remove when no longer needed
  // await handle.remove();
};

API Reference

Section titled “API Reference”

isAvailable(options)

Section titled “isAvailable(options)”

Checks if biometric authentication is available on the device.

interface IsAvailableOptions {
  useFallback: boolean;
}


interface AvailableResult {
  isAvailable: boolean;
  authenticationStrength: AuthenticationStrength; // STRONG | WEAK | NONE
  biometryType: BiometryType;
  deviceIsSecure: boolean;
  strongBiometryIsAvailable: boolean;
  errorCode?: number;
}

verifyIdentity(options)

Section titled “verifyIdentity(options)”

Prompts for biometric authentication.

interface BiometricOptions {
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
  useFallback?: boolean;
  fallbackTitle?: string;
  maxAttempts?: number; // Android only
  allowedBiometryTypes?: BiometryType[];
}

setCredentials(options)

Section titled “setCredentials(options)”

Stores credentials. Use accessControl to enforce biometric-only retrieval on supported platforms.

interface SetCredentialOptions {
  username: string;
  password: string;
  server: string;
  accessControl?: AccessControl;
}

getSecureCredentials(options)

Section titled “getSecureCredentials(options)”

Gets stored credentials only when authentication succeeds for protected entries.

interface GetSecureCredentialsOptions {
  server: string;
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
}

isCredentialsSaved(options)

Section titled “isCredentialsSaved(options)”

Checks if credentials exist for a server entry.

interface IsCredentialsSavedOptions {
  server: string;
}


interface IsCredentialsSavedResult {
  isSaved: boolean;
}

deleteCredentials(options)

Section titled “deleteCredentials(options)”

Deletes stored credentials for a server entry.

interface DeleteCredentialOptions {
  server: string;
}

addListener(‘biometryChange’, …)

Section titled “addListener(‘biometryChange’, …)”

Listen for biometric changes and resume flows safely.

const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  // result: AvailableResult
});

Platform differences

Section titled “Platform differences”

iOS

Section titled “iOS”
  • Supports Face ID and Touch ID
  • useFallback follows passcode fallback behavior as configured

Android

Section titled “Android”
  • Supports fingerprint, face, iris, and PIN/pattern/password flows
  • Android constraints apply for fallback UI and biometric type restrictions

Best Practices

Section titled “Best Practices”
  1. Always check availability first
  2. Use full result data to choose secure routes
  3. Prefer secure credential modes for sensitive data
  4. Handle cancellation and errors gracefully
  5. Remove listeners when they are no longer needed
Section titled “Related Documentation”