본문 바로가기

@capgo/capacitor-native-biometric

Android 및 iOS용 안전한 자격 증명 저장 및 생체 인증 기반 액세스.

Native Biometric은 iOS와 Android를 위한 안전한 자격 증명 저장소입니다. 자격 증명을 네이티브 Keychain 또는 Keystore에 저장하며, 민감한 값이 반환되기 전에 생체 인증을 요구할 수 있습니다. Ionic Identity Vault의 credential-vault 플로우를 직접 대체하며, 앱이 타임아웃, 라이프사이클, 프라이버시 스크린, 사용자 지정 비밀번호 정책을 제어합니다.

이 플러그인의 메이저 버전은 Capacitor를 따릅니다: Capacitor 8용 v8(활발히 유지보수 중), Capacitor 7용 v7(요청 시 유지보수).

  • setCredentials 및 getCredentials - 특정 서버의 인증 정보를 안전하게 저장하고 불러옵니다.
  • getSecureCredentials - 네이티브 생체 인증을 거친 후에만 인증 정보를 읽을 수 있습니다.
  • isCredentialsSaved 및 deleteCredentials - 온보딩, 잠금 상태, 로그아웃 플로우를 구현할 수 있습니다.
  • isAvailable 및 verifyIdentity - 인증 가능 여부를 확인하고 필요 시 사용자에게 프롬프트를 표시합니다.
메서드설명
isAvailable생체 인증 하드웨어 사용 가능 여부를 확인합니다.
addListener앱이 백그라운드에서 복귀할 때 호출되는 리스너를 추가합니다. 앱이 백그라운드에 있는 동안 생체 인증 사용 가능 여부가 변경되었는지(예: 사용자가 생체 인증을 등록/해제) 감지하는 데 유용합니다.
verifyIdentity사용자에게 생체 인증을 요청합니다.
getCredentials지정된 서버의 저장된 인증 정보를 가져옵니다.
setCredentials지정된 서버의 인증 정보를 저장합니다.
deleteCredentials지정된 서버의 저장된 인증 정보를 삭제합니다.
getSecureCredentials지정된 서버에 저장된 자격 증명을 생체 인증을 통해 가져옵니다. 자격 증명은 accessControl이 BIOMETRY_CURRENT_SET 또는 BIOMETRY_ANY로 설정된 상태로 저장되어 있어야 합니다.
isCredentialsSaved지정된 서버에 대한 인증 정보가 이미 저장되어 있는지 확인합니다.
getPluginVersion네이티브 Capacitor 플러그인 버전을 가져옵니다.

처리 시 다음 값을 사용하세요 biometricError 결과에서 authenticate.

값Code플랫폼의미
UNKNOWN_ERROR0Android, iOS알 수 없는 오류가 발생했습니다.
BIOMETRICS_UNAVAILABLE1Android, iOS하드웨어가 없거나 사용할 수 없어 생체 인증을 사용할 수 없습니다.
USER_LOCKOUT2Android, iOS인증 시도 횟수 초과로 사용자가 잠겼습니다.
BIOMETRICS_NOT_ENROLLED3Android, iOS기기에 등록된 생체 정보가 없습니다.
USER_TEMPORARY_LOCKOUT4Android사용자가 일시적으로 잠겼습니다(보통 30초).
AUTHENTICATION_FAILED10Android, iOS인증에 실패했습니다.
APP_CANCEL11iOS앱에서 인증 플로우를 취소했습니다.
INVALID_CONTEXT12iOS인증 컨텍스트가 유효하지 않습니다.
NOT_INTERACTIVE13iOS인증이 대화형으로 진행되지 않았습니다.
PASSCODE_NOT_SET14Android, iOS기기 암호, PIN 또는 대체 인증 수단이 설정되어 있지 않습니다.
SYSTEM_CANCEL15Android, iOS화면 잠금 등으로 인해 시스템에서 인증을 취소했습니다.
USER_CANCEL16Android, iOS사용자가 인증을 취소했습니다.
USER_FALLBACK17Android, iOS사용자가 대체 인증 수단을 선택했습니다.

이 레퍼런스는 다음에서 동기화됩니다. src/definitions.ts 에서 capacitor-native-biometric.

@capgo/capacitor-native-biometric에서 계속하기

“@capgo/capacitor-native-biometric에서 계속하기” 섹션

사용 중이라면 @capgo/capacitor-native-biometric 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-native-biometric 사용하기 @capgo/capacitor-native-biometric 사용하기에서 네이티브 기능을 위해, @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 2단계 인증 2단계 인증(Two-factor authentication)의 구현 세부 사항은, SSO (기업용) SSO (Enterprise)의 구현 세부 사항은.