React SDK

1. 설치

npm i @h6s-ai/react

peer dependency: react ≥ 18, react-dom ≥ 18.

2. 토큰 발급

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

3. headless hook

루트 @h6s-ai/react 의 useRegistration 은 UI 를 그리지 않습니다. 파트너 화면에서 입력칸·버튼을 직접 렌더하고, hook 은 세션 메타 조회·암호화·제출 상태만 제공합니다.

import { useRegistration } from "@h6s-ai/react";

export function RegisterCredential({ sessionToken }: { sessionToken: string }) {
  const reg = useRegistration({
    sessionToken,
    autoLoad: true,
  });

  return (
    <button
      type="button"
      disabled={reg.isBusy}
      onClick={() =>
        reg.registerWithLogin({
          providerCode: "kb_bank",
          fields: { loginId, loginPw },
        })
      }
    >
      자격증명 등록
    </button>
  );
}

공동인증서 에이전트 설치 링크가 필요하면 React 패키지에서 같은 헬퍼를 가져옵니다. 모바일·서버 환경에서는 null 을 반환합니다.

import { useEffect, useState } from "react";
import { getCertificateAgentDownloadUrl } from "@h6s-ai/react";

export function AgentInstallLink() {
  const [href, setHref] = useState<string | null>(null);

  useEffect(() => {
    setHref(getCertificateAgentDownloadUrl());
  }, []);

  if (!href) return null;

  return <a href={href}>공동인증서 에이전트 설치</a>;
}

4. embedded 버튼 컴포넌트

h6s 가 UI 를 렌더하는 관리형 흐름은 @h6s-ai/react/embedded 서브패스를 사용합니다. 가장 단순한 경로입니다. 버튼을 누르면 모달이 열리고 iframe 모드에서는 등록이 끝난 뒤 자동으로 닫힙니다. 모바일 fallback 으로 열린 hosted page 는 SDK 콜백을 실행하지 않습니다.

import { RegistrationButton } from "@h6s-ai/react/embedded";

export function ConnectBank({ sessionToken }: { sessionToken: string }) {
  return (
    <RegistrationButton
      sessionToken={sessionToken}
      onSuccess={({ credentialId }) => { /* 등록 완료 후 처리 */ }}
      onExit={({ reason }) => { /* reason 별 처리 (아래 표) */ }}
      className="rounded-md bg-black px-4 py-2 text-white"
    >
      자격증명 등록
    </RegistrationButton>
  );
}

5. 이벤트 처리

onSuccess 의 credentialId 를 파트너 시스템의 사용자와 연결합니다. onExit 은 reason 으로 종료 사유를 구분합니다. 두 콜백은 동시에 발생하지 않습니다. 두 콜백은 iframe 모드에서만 실행되며, 모바일 fallback 은 세션 상태 polling(GET /api/v1/registration-sessions/{id})으로 완료를 확인합니다.

다른 진입점

• useRegistrationModal: 직접 만든 버튼에서 모달을 엽니다.
• Registration: 자체 패널 안에 등록 화면을 넣습니다.