took.WSS 문서
Host SDK

SDK 설치·초기화

기관 서버에서 받은 세션으로 지갑 iframe을 연결합니다.

SDK 설치

# npm 공개 이후
npm install @took-wss/host-sdk

JavaScript·TypeScript에서 사용합니다. 브라우저 DOM과 postMessage가 필요하므로 서버 렌더링 중에는 초기화하지 않습니다.

초기화하기

HTML에 <iframe id="wallet" title="기관 지갑"></iframe>을 추가하고, 기관 서버에서 받은 세션과 허용된 BFF 주소를 전달합니다.

connect-wallet.ts
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에 선언하세요.

필수 옵션

이름타입설명
frameHTMLIFrameElement지갑을 표시할 iframe 객체. null을 허용하지 않습니다.
walletOriginstring지갑 URL의 정확한 origin. 수신 출처와 발신 대상을 제한합니다.
sessionTokenstring기관 서버에서 발급한 단기 세션 토큰. 기관 키와 다릅니다.
bffUrlstring해당 환경의 허용된 BFF 주소.
hostCapabilitiesHostCapabilities호스트의 화면 소유권과 지원 기능. 전체 필드 참고.

필수 옵션에는 기본값이 없습니다. 전체 옵션·메서드

연결이 되지 않을 때

  • 호스트·지갑·BFF의 허용 origin 설정을 확인합니다.
  • 세션의 만료 시각을 확인하고 기관 서버에서 새 세션을 발급합니다.
  • 호스트 헤더·탭·안전 영역 설정이 기관 manifest와 일치하는지 확인합니다.
  • ready와 bootstrapped를 구분하고 오류 이벤트를 처리합니다.

이 페이지에서