Appearance
WebToApp 구현
모바일 신분증 WebToApp 연동은 AppToApp의 direct mode 방식과 동일하게 SP 서버로 VP를 제출하는 구조예요. VP 제출 확인 방식은 아래 두 가지 중 선택할 수 있어요.
- 자동 확인: 서비스 웹페이지에서 SP서버로 응답을 주기적으로 확인
- 수동 확인: 모바일 신분증 앱 종료 후 ‘인증 확인’ 버튼을 눌러 결과 확인
1. 호출 방식
Android
- 방식 1 (URL Scheme)
html
window.location.href =
'mobileid://verify?data_type=byte&data=m200Base64&clientScheme=';- 방식 2 (Intent 방식)
html
<a
href="intent://verify?data_type=byte&data=m200Base64#Intent;scheme=mobileid;action=android.intent.action.VIEW;category=android.intent.category.BROWSABLE;package=kr.go.mobileid;end"
>
신분증 앱 실행
</a>| 파라미터 | 설명 |
|---|---|
data_type | 선택, string 또는 byte 가능 |
data | 필수, Base64 인코딩된 M200 메시지 |
clientScheme | 선택, 신분증 앱 종료 후 돌아올 URL Scheme |
Intent 방식은 앱 미설치 시 자동으로 플레이스토어 이동, URL Scheme 방식은 그렇지 않아요.
iOS
- 방식 1 (URL Scheme)
javascript
window.location.href =
"MobileID://verify?mode=direct&data=<BASE64_ENCODED_M200>&clientScheme=";- 방식 2 (Universal Link)
→3.3 Universal Link 방식참조
| 파라미터 | 설명 |
|---|---|
mode | 필수, direct 또는 indirect |
data | 필수, Base64 인코딩된 M200 메시지 |
clientScheme | 필수, 앱 종료 후 호출할 URL Scheme. 없을 경우 공백 |
2. 미설치 시 예외처리 방안
URL Scheme 방식으로 신분증 앱 호출 시 앱이 미설치된 경우, 대응이 어렵기 때문에 별도 예외처리 필요해요.
대응 방안:
- 일정 시간 내 앱 응답 없으면 안내문구 표시
clientScheme설정을 통해 결과 확인 로직 분리 구현
예시: 간편인증 인증 진행화면
3. 에러코드
아래는 VP 제출 시 발생할 수 있는 주요 에러코드 목록이에요:
| 코드 | 이름 | 설명 |
|---|---|---|
| 20001 | Unexpected message format | JSON 형식이 아님 |
| 20002 | Missing mandatory item | 필수 항목 누락 |
| 20100 | Invalid data | 유효하지 않은 데이터 |
| 20101 | Invalid result | result 값이 true/false 아님 |
| 20102 | Encoding error | 인코딩 오류 |
| 20103 | Mismatching trxcode | 거래코드 불일치 |
| 20104 | Unsupported image type | 이미지 타입 미지원 |
| 20201 | Message sequence error | 메시지 순서 오류 |
| 20202 | Timeout error | 유효시간 초과 |
| 20203 | Unknown disconnect | 앱 강제 종료 등 |
| 20300 | Invalid profile data | 프로필 데이터 오류 |
| 20301 | VC not exists | 발급된 VC 없음 |
| 20302 | No VC for allowed issuers | 해당 발급자 VC 없음 |
| 20303 | Missing mandatory item in profile | 프로필 내 필수 항목 누락 |
| 20304 | Missing nonce in profile | 프로필에 nonce 없음 |
| 20305 | Missing proof in profile | 프로필에 proof 없음 |
| 20306 | Profile signature validation fail | 서명 검증 실패 |
| 20307 | Fail to get DID document | DID 문서 조회 실패 |
| 20308 | Fail to get VC Status | VC 상태 업데이트 실패 |
| 20401 | ZKP error 1 | 영지식 정보 검색 실패 |
| 20402 | ZKP error 2 | 나이 조건 불일치 |
| 20403 | ZKP error 3 | Credential schema 조회 실패 |
| 20501 | Fail to get profile | 프로필 조회 실패 |
| 20502 | Fail to get image | 이미지 조회 실패 |
| 20503 | Fail to submit VP | VP 제출 실패 |
| 20511 | Fail to get sig-profile | 전자서명 프로필 실패 |
| 20513 | Fail to submit sig-vp | 전자서명 VP 제출 실패 |
| 20601 | VP proof fail | VP 생성 실패 |
| 20602 | Make signature fail | 서명 생성 실패 |
| 20701 | BLE incorrect password | BLE 비밀번호 오류 |
| 20901 | Cancel by user | 사용자 취소 |
| 20903 | Transmit size exceeded | 전송 사이즈 초과 |
| 90001 | User authentication fail | 사용자 인증 실패 |
| 90002 | Invalid app version | 앱 버전 오류 |
| 99999 | Unknown error | 알 수 없는 오류 |