Host SDK
WssHostClient
초기화 옵션, 호스트 기능 선언과 클라이언트 생명주기입니다.
Host SDK 0.1.0 기준입니다.
생성자
new WssHostClient(options)는 클라이언트 객체를 반환합니다. 생성만으로 메시지 수신을 시작하지 않으며, 연결에는 start()가 필요합니다. 필수 옵션과 예제를 확인하세요.
메서드
| 메서드 | 인수 | 반환값 | 동작 |
|---|---|---|---|
| start() | 없음 | void | window의 message 리스너를 등록합니다. 이미 시작한 경우 중복 등록하지 않습니다. |
| stop() | 없음 | void | 메시지 리스너를 제거합니다. 이미 중지한 경우 그대로 반환합니다. |
stop()은 iframe 제거, 세션 폐기 또는 지갑 내부 작업 취소를 수행하지 않습니다. 초기화 완료 상태도 리셋하지 않으므로 iframe 재로드·고객 변경·세션 교체에는 새 인스턴스를 사용하세요. 중지 이후 완료된 비동기 콜백의 응답은 전송하지 않습니다.
HostCapabilities
다음 필드는 모두 필수 boolean이며 null과 기본값이 없습니다. 기능의 존재 여부를 선언하며, 값을 true로 바꾼 것만으로 호스트 기능이 구현되지는 않습니다.
| 필드 | 의미 |
|---|---|
| handlesSafeArea | 호스트가 안전 영역을 처리합니다. |
| rendersRootHeader | 호스트가 최상위 헤더를 표시합니다. |
| rendersRootTabs | 호스트가 최상위 탭을 표시합니다. |
| canScanQr | 호스트가 QR 스캔을 지원합니다. |
| canUseContacts | 호스트가 연락처 사용을 지원합니다. |
| canOpenRecovery | 호스트가 복구 진입을 지원합니다. |
| canLinkExternalWallet | 외부 지갑 연결을 지원합니다. |
| canSecureWalletImport | 보안 지갑 가져오기를 지원합니다. |
| canCreateSecureSarWallet | 보안 SAR 지갑 생성을 지원합니다. |
헤더·탭·안전 영역 소유권은 기관 manifest와 일치해야 합니다.
선택 콜백
| 옵션 | 호출 조건 | 계약 |
|---|---|---|
| onEvent | 검증을 통과한 지갑 메시지 수신 | (event: WalletToHostMessage) => void |
| requestAuthentication | 호스트 인증 요청 | (purpose: HostAuthenticationPurpose) => Promise<HostAuthenticationResult> |
| requestSecureSarWalletCreation | 보안 SAR 생성 요청 | () => Promise<SecureSarWalletCreationResult> |
| requestSecureWalletImport | 보안 가져오기 요청 | (method: WalletImportMethod) => Promise<SecureWalletImportResult> |
| requestSecureTransactionSignature | 보안 거래 서명 요청 | (request: SecureTransactionSigningRequest) => Promise<SecureTransactionSigningResult> |
인증·생성·가져오기·서명 콜백이 없거나 예외를 던지면 SDK는 해당 요청에 { status: 'cancelled' }를 반환합니다. 인증 목적은 wallet-provisioning, transfer-approval, wallet-recovery입니다.
출처와 프로토콜 검사
SDK는 walletOrigin, frame.contentWindow, 메시지 형태와 프로토콜 버전을 검사합니다. 일치하지 않는 메시지는 콜백으로 전달하지 않습니다. origin을 와일드카드로 대체하지 마세요.