Vanilla JS SDK

1. 설치

npm i @h6s-ai/web

빌드 도구 없이 쓰려면 script tag 로 로드합니다. 같은 API 가 window.h6s 에 노출됩니다.

<script src="https://js.h6s.ai/sdk/v1/h6s.js"></script>

v1 경로는 보안 패치가 자동 전파됩니다 (5분 캐시). 특정 버전 고정이 필요하면 js.h6s.ai/sdk/v1.0.3/h6s.js 와 SRI hash 를 사용합니다.

2. 토큰 발급

sessionToken 은 파트너 백엔드가 API 키로 발급합니다 — 브라우저에서는 만들지 않습니다. 발급 요청·응답 형식은 SDK 개요의 백엔드 단계를 참고하세요.

3. headless 컨트롤러

루트 @h6s-ai/web 는 UI 를 그리지 않습니다. 파트너 화면에서 인증서 목록·입력칸·버튼을 직접 렌더하고, SDK 는 메타 조회·인증서 조회·암호화· 제출만 맡습니다.

import { createRegistration } from "@h6s-ai/web";

const reg = createRegistration({ sessionToken });

const metadata = await reg.load();

if (metadata.options.some((option) => option.kind === "CERTIFICATE")) {
  const certs = await reg.certificates.list();
  await reg.certificates.register({
    certificateId: certs[0].id,
    password,
  });
}

await reg.login.register({
  providerCode: "kb_bank",
  fields: { loginId, loginPw },
});

공동인증서 에이전트 설치 링크가 필요하면 플랫폼별 다운로드 URL 을 SDK 에서 바로 조회합니다. 모바일·서버 환경에서는 null 을 반환합니다.

import { getCertificateAgentDownloadUrl } from "@h6s-ai/web";

const href = getCertificateAgentDownloadUrl();

if (href) {
  document.querySelector("#agent-install").setAttribute("href", href);
}

4. embedded 모달 열기

h6s 가 UI 를 렌더하는 관리형 흐름은 @h6s-ai/web/embedded 서브패스를 사용합니다. 토큰을 받아 모달을 엽니다. 데스크탑은 iframe 모달, 모바일은 호스팅 페이지로 자동 전환됩니다. 모바일 전환 뒤에는 현재 페이지의 SDK 콜백이 실행되지 않습니다.

import { openRegistrationModal } from "@h6s-ai/web/embedded";

const handle = openRegistrationModal({
  sessionToken,                              // 백엔드에서 발급받은 1회용 토큰
  onSuccess: ({ credentialId }) => {
    // credentialId 를 파트너 시스템의 사용자와 연결합니다
    location.href = "/done?credential=" + credentialId;
  },
  onExit: ({ reason }) => {
    // reason 별 처리 (아래 표 참고)
  },
});

// 필요하면 직접 닫을 수 있습니다
// handle.close();

script tag 로 로드했다면 같은 호출을 window.h6s 로 합니다.

<script src="https://js.h6s.ai/sdk/v1/h6s.js"></script>
<button id="register">자격증명 등록</button>
<script>
  document.getElementById("register").onclick = () => {
    window.h6s.openRegistrationModal({
      sessionToken: window.SESSION_TOKEN,   // 서버 렌더 시 주입
      onSuccess: ({ credentialId }) => console.log("done", credentialId),
    });
  };
</script>

5. 이벤트 처리

onSuccess 의 credentialId 를 파트너 시스템의 사용자와 연결합니다. onExit 은 reason 으로 종료 사유를 구분합니다. 두 콜백은 동시에 발생하지 않습니다. 두 콜백은 iframe 모드에서만 실행됩니다.

다른 진입점

• mountRegistration: 자체 패널 안에 등록 화면을 넣습니다.
• openHostedRegistration: 등록 페이지를 새 화면으로 엽니다.