Getting Started

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 스킬을 추가하려면 다음 명령어를 사용하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

다음 명령어를 사용하여 플러그인을 설치하고 아래에 플랫폼별로 설명된 지침을 따르세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project.

만약 Manual Setup을 선호한다면, 다음 명령어를 실행하고 아래에 플랫폼별로 설명된 지침을 따르세요:

bun add @capgo/capacitor-native-biometric
bunx cap sync

Import

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

API 개요

isAvailable

비омет릭 인증 장치가 사용 가능한지 확인합니다.

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

await NativeBiometric.isAvailable();

verifyIdentity

사용자에게 비омет릭 인증을 요청합니다.

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

await NativeBiometric.verifyIdentity();

getCredentials

__CAPGO_KEEP_2__을 위한 저장된 자격증명을 얻습니다.

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

await NativeBiometric.getCredentials({} as GetCredentialOptions);

setCredentials

__CAPGO_KEEP_2__를 위한 저장된 자격증명을 저장합니다.

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

await NativeBiometric.setCredentials({} as SetCredentialOptions);

deleteCredentials

__CAPGO_KEEP_2__를 위한 저장된 자격증명을 삭제합니다.

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

await NativeBiometric.deleteCredentials({} as DeleteCredentialOptions);

getSecureCredentials

__CAPGO_KEEP_2__를 위한 저장된 자격증명을 얻습니다. (생체 인증이 필요합니다.) 생체 인증을 사용한 자격증명이 저장된 경우에만 사용할 수 있습니다.

iOS에서 시스템은 보호된 Keychain 항목에 접근할 때 자동으로 생체 인증 프롬프트를 표시합니다. 안드로이드에서는 BiometricPrompt가 credential.decryptionKey와 바인딩된 암호화 키로 credential.decryptionKey를 해독합니다.

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

await NativeBiometric.getSecureCredentials({} as GetSecureCredentialsOptions);

isCredentialsSaved

서버에 저장된 자격 증명이 있는지 확인합니다.

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

await NativeBiometric.isCredentialsSaved({} as IsCredentialsSavedOptions);

타입 참조

IsAvailableOptions

export interface IsAvailableOptions {
  /**
   * Only for iOS.
   * Specifies if should fallback to passcode authentication if biometric authentication is not available.
   * On Android, this parameter is ignored due to BiometricPrompt API constraints:
   * DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
   */
  useFallback: boolean;
}

AvailableResult

isAvailable() 메서드의 생체 인증 인증 가능성 여부를 나타내는 결과입니다.

export interface AvailableResult {
  /**
   * Whether authentication is available (biometric or fallback if useFallback is true)
   */
  isAvailable: boolean;
  /**
   * The strength of available authentication method (STRONG, WEAK, or NONE)
   */
  authenticationStrength: AuthenticationStrength;
  /**
   * The primary biometry type available on the device.
   * On Android devices with multiple biometry types, this returns MULTIPLE.
   * Use this for display purposes only - always use isAvailable for logic decisions.
   */
  biometryType: BiometryType;
  /**
   * Whether the device has a secure lock screen (PIN, pattern, or password).
   * This is independent of biometric enrollment.
   */
  deviceIsSecure: boolean;
  /**
   * Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong)
   * is specifically available, separate from weak biometry or device credentials.
   */
  strongBiometryIsAvailable: boolean;
  /**
   * Error code from BiometricAuthError enum. Only present when isAvailable is false.
   * Indicates why biometric authentication is not available.
   * @see BiometricAuthError
   */
  errorCode?: BiometricAuthError;
}

BiometryChangeListener

비омет리 변화 리스너 콜백 타입.

export type BiometryChangeListener = (result: AvailableResult) => void;

BiometricOptions

export interface BiometricOptions {
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
  /**
   * Only for iOS.
   * Specifies if should fallback to passcode authentication if biometric authentication fails.
   * On Android, this parameter is ignored due to BiometricPrompt API constraints:
   * DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
   */
  useFallback?: boolean;
  /**
   * Only for iOS.
   * Set the text for the fallback button in the authentication dialog.
   * If this property is not specified, the default text is set by the system.
   */
  fallbackTitle?: string;
  /**
   * Only for Android.
   * Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5.
   * @default 1
   */
  maxAttempts?: number;
  /**
   * Only for Android.
   * Specify which biometry types are allowed for authentication.
   * If not specified, all available types will be allowed.
   * @example [BiometryType.FINGERPRINT, BiometryType.FACE_AUTHENTICATION]
   */
  allowedBiometryTypes?: BiometryType[];
}

GetCredentialOptions

export interface GetCredentialOptions {
  server: string;
}

Credentials

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

SetCredentialOptions

export interface SetCredentialOptions {
  username: string;
  password: string;
  server: string;
  /**
   * Access control level for the stored credentials.
   * When set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY, the credentials are
   * hardware-protected and require biometric authentication to access.
   *
   * On iOS, this adds SecAccessControl to the Keychain item.
   * On Android, this creates a biometric-protected Keystore key and requires
   * BiometricPrompt authentication for both storing and retrieving credentials.
   *
   * @default AccessControl.NONE
   * @since 8.4.0
   */
  accessControl?: AccessControl;
}

DeleteCredentialOptions

export interface DeleteCredentialOptions {
  server: string;
}

GetSecureCredentialsOptions

export interface GetSecureCredentialsOptions {
  server: string;
  /**
   * Reason for requesting biometric authentication.
   * Displayed in the biometric prompt on both iOS and Android.
   */
  reason?: string;
  /**
   * Title for the biometric prompt.
   * Only for Android.
   */
  title?: string;
  /**
   * Subtitle for the biometric prompt.
   * Only for Android.
   */
  subtitle?: string;
  /**
   * Description for the biometric prompt.
   * Only for Android.
   */
  description?: string;
  /**
   * Text for the negative/cancel button.
   * Only for Android.
   */
  negativeButtonText?: string;
}

IsCredentialsSavedOptions

export interface IsCredentialsSavedOptions {
  server: string;
}

IsCredentialsSavedResult

export interface IsCredentialsSavedResult {
  isSaved: boolean;
}

AuthenticationStrength

export enum AuthenticationStrength {
  /**
   * No authentication available, even if PIN is available but useFallback = false
   */
  NONE = 0,
  /**
   * Strong authentication: Face ID on iOS, fingerprints on devices that consider fingerprints strong (Android).
   * Note: PIN/pattern/password is NEVER considered STRONG, even when useFallback = true.
   */
  STRONG = 1,
  /**
   * Weak authentication: Face authentication on Android devices that consider face weak,
   * or PIN/pattern/password if useFallback = true (PIN is always WEAK, never STRONG).
   */
  WEAK = 2,
}

Source Of Truth

이 페이지는 플러그인의 src/definitions.ts. API이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속하기

__CAPGO_KEEP_0__을 사용하고 있다면 Getting Started 인증 및 계정 흐름을 계획하고 연결하려면 capgo/capacitor-native-biometric을 @capgo/capacitor-native-biometric에서 사용하세요. capgo/capacitor-native-biometric에서 사용하는 native 기능을 위한 @capgo/capacitor-native-biometric입니다. capgo/capacitor-social-login을 @capgo/capacitor-social-login에서 사용하세요. capgo/capacitor-social-login에서 사용하는 implementation detail을 위한 @capgo/capacitor-social-login입니다. capgo/capacitor-passkey을 @capgo/capacitor-passkey에서 사용하세요. capgo/capacitor-passkey에서 사용하는 implementation detail을 위한 @capgo/capacitor-passkey입니다. @capgo/capacitor-native-생체인식 for the implementation detail in @capgo/capacitor-native-생체인식, and 두 단계 인증 for the implementation detail in 두 단계 인증.