개요
“개요” 섹션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- 인증 가능 여부를 확인하고 필요 시 사용자에게 프롬프트를 표시합니다.
공개 API
“Public API” 섹션| 메서드 | 설명 |
|---|---|
isAvailable | 생체 인증 하드웨어 사용 가능 여부를 확인합니다. |
addListener | 앱이 백그라운드에서 복귀할 때 호출되는 리스너를 추가합니다. 앱이 백그라운드에 있는 동안 생체 인증 사용 가능 여부가 변경되었는지(예: 사용자가 생체 인증을 등록/해제) 감지하는 데 유용합니다. |
verifyIdentity | 사용자에게 생체 인증을 요청합니다. |
getCredentials | 지정된 서버의 저장된 인증 정보를 가져옵니다. |
setCredentials | 지정된 서버의 인증 정보를 저장합니다. |
deleteCredentials | 지정된 서버의 저장된 인증 정보를 삭제합니다. |
getSecureCredentials | 지정된 서버에 저장된 자격 증명을 생체 인증을 통해 가져옵니다. 자격 증명은 accessControl이 BIOMETRY_CURRENT_SET 또는 BIOMETRY_ANY로 설정된 상태로 저장되어 있어야 합니다. |
isCredentialsSaved | 지정된 서버에 대한 인증 정보가 이미 저장되어 있는지 확인합니다. |
getPluginVersion | 네이티브 Capacitor 플러그인 버전을 가져옵니다. |
참조 값
“참조 값” 섹션처리 시 다음 값을 사용하세요 biometricError 결과에서 authenticate.
생체 인증 오류
“생체 인증 오류” 섹션| 값 | Code | 플랫폼 | 의미 |
|---|---|---|---|
UNKNOWN_ERROR | 0 | Android, iOS | 알 수 없는 오류가 발생했습니다. |
BIOMETRICS_UNAVAILABLE | 1 | Android, iOS | 하드웨어가 없거나 사용할 수 없어 생체 인증을 사용할 수 없습니다. |
USER_LOCKOUT | 2 | Android, iOS | 인증 시도 횟수 초과로 사용자가 잠겼습니다. |
BIOMETRICS_NOT_ENROLLED | 3 | Android, iOS | 기기에 등록된 생체 정보가 없습니다. |
USER_TEMPORARY_LOCKOUT | 4 | Android | 사용자가 일시적으로 잠겼습니다(보통 30초). |
AUTHENTICATION_FAILED | 10 | Android, iOS | 인증에 실패했습니다. |
APP_CANCEL | 11 | iOS | 앱에서 인증 플로우를 취소했습니다. |
INVALID_CONTEXT | 12 | iOS | 인증 컨텍스트가 유효하지 않습니다. |
NOT_INTERACTIVE | 13 | iOS | 인증이 대화형으로 진행되지 않았습니다. |
PASSCODE_NOT_SET | 14 | Android, iOS | 기기 암호, PIN 또는 대체 인증 수단이 설정되어 있지 않습니다. |
SYSTEM_CANCEL | 15 | Android, iOS | 화면 잠금 등으로 인해 시스템에서 인증을 취소했습니다. |
USER_CANCEL | 16 | Android, iOS | 사용자가 인증을 취소했습니다. |
USER_FALLBACK | 17 | Android, iOS | 사용자가 대체 인증 수단을 선택했습니다. |
Source of Truth
“Source Of Truth” 섹션이 레퍼런스는 다음에서 동기화됩니다. 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)의 구현 세부 사항은.