Host SDK
SDK 설치·초기화
기관 서버에서 받은 세션으로 지갑 iframe을 연결합니다.
SDK 설치
# npm 공개 이후
npm install @took-wss/host-sdkJavaScript·TypeScript에서 사용합니다. 브라우저 DOM과 postMessage가 필요하므로 서버 렌더링 중에는 초기화하지 않습니다.
초기화하기
HTML에 <iframe id="wallet" title="기관 지갑"></iframe>을 추가하고, 기관 서버에서 받은 세션과 허용된 BFF 주소를 전달합니다.
import { WssHostClient } from '@took-wss/host-sdk';
type Session = {
sessionToken: string;
expiresAt: string;
walletUrl: string;
};
export function connectWallet(session: Session, bffUrl: string) {
const frame = document.querySelector<HTMLIFrameElement>('#wallet');
if (!frame) throw new Error('지갑 iframe이 필요합니다.');
const client = new WssHostClient({
frame,
walletOrigin: new URL(session.walletUrl).origin,
sessionToken: session.sessionToken,
bffUrl,
// 아래는 호스트가 헤더·탭·안전 영역을 소유하는 예시입니다.
// 실제 기관 manifest와 호스트 구현에 맞춰 설정하세요.
hostCapabilities: {
handlesSafeArea: true,
rendersRootHeader: true,
rendersRootTabs: true,
canScanQr: false,
canUseContacts: false,
canOpenRecovery: false,
canLinkExternalWallet: false,
canSecureWalletImport: false,
canCreateSecureSarWallet: false,
},
onEvent(event) {
if (event.type === 'took-wss:bootstrapped') {
console.info('지갑 연결 완료');
}
if (event.type === 'took-wss:error') {
console.error('지갑 연결 오류:', event.code);
}
},
});
client.start();
frame.src = session.walletUrl;
return () => client.stop();
}이 예제는 연결까지만 처리합니다. 지갑 생성·가져오기·서명에는 호스트 콜백이 필요합니다. 구현한 기능만 capability에 선언하세요.
필수 옵션
| 이름 | 타입 | 설명 |
|---|---|---|
| frame | HTMLIFrameElement | 지갑을 표시할 iframe 객체. null을 허용하지 않습니다. |
| walletOrigin | string | 지갑 URL의 정확한 origin. 수신 출처와 발신 대상을 제한합니다. |
| sessionToken | string | 기관 서버에서 발급한 단기 세션 토큰. 기관 키와 다릅니다. |
| bffUrl | string | 해당 환경의 허용된 BFF 주소. |
| hostCapabilities | HostCapabilities | 호스트의 화면 소유권과 지원 기능. 전체 필드 참고. |
필수 옵션에는 기본값이 없습니다. 전체 옵션·메서드
연결이 되지 않을 때
- 호스트·지갑·BFF의 허용 origin 설정을 확인합니다.
- 세션의 만료 시각을 확인하고 기관 서버에서 새 세션을 발급합니다.
- 호스트 헤더·탭·안전 영역 설정이 기관 manifest와 일치하는지 확인합니다.
ready와bootstrapped를 구분하고 오류 이벤트를 처리합니다.