3. 렌더 위젯

렌더 위젯

'토큰 발급' API를 통해 발급받은 토큰을 사용하여 위젯을 렌더링합니다. 위젯은 지갑 연결 및 메시지 서명(Signature Proof) 화면을 자동으로 제공합니다.

컴포넌트 로드

<script type="module" src={Widget Script}></script>

요소 추가

<wallet-verifier
  id="wv"
  data-token={token}
  data-language="en"
>
</wallet-verifier>

Vanilla JS 예시

<div id="wallet-verifier"></div>
<script type="module" 
  src="WIDGET_SCRIPT_URL"
></script>
<script>
  const el = document.createElement('wallet-verifier')

  el.setAttribute('data-token', 'YOUR_TOKEN')
  // 지원 언어: en, et, cs, hu, pl, ru, uk, es, ko
  el.setAttribute('data-language', 'en')

  el.addEventListener('verification-complete', (event) => {
    console.log('complete', event.detail)
  })
  el.addEventListener('verification-error', (event) => {
    console.log('error', event.detail)
  })

  document.getElementById('wallet-verifier').appendChild(el)
</script>

React 예시

import { useEffect, useRef } from 'react'

export default function WalletVerifierWidget({ token }) {
  const elRef = useRef(null)

  useEffect(() => {
    const script = document.createElement('script')
    script.type = 'module'
    script.src = 'WIDGET_SCRIPT_URL'
    document.body.appendChild(script)

    return () => {
      document.body.removeChild(script)
    }
  }, [])

  useEffect(() => {
    const el = elRef.current

    if (!el) return

    const onComplete = (event) => {
      const detail = event.detail
      console.log('complete', detail)
    }

    const onError = (event) => {
      const detail = event.detail
      console.log('error', detail)
    }

    el.addEventListener('verification-complete', onComplete)
    el.addEventListener('verification-error', onError)

    return () => {
      el.removeEventListener('verification-complete', onComplete)
      el.removeEventListener('verification-error', onError)
    }
  }, [])

  return (
    <wallet-verifier
      ref={elRef}
      data-token={token}
      // 지원 언어: en, et, cs, hu, pl, ru, uk, es, ko
      data-language="en"
    />
  )
}

클라이언트 이벤트 처리

클라이언트 이벤트는 성공 시 verification-complete, 실패 시 verification-error로 구성됩니다. 성공 시 콜백을 통해 결과가 전달되며, '검증 결과 조회' API를 통해서도 확인할 수 있습니다. 실패 시에는 콜백이 전송되지 않습니다.

검증 성공 이벤트

검증이 성공하면 위젯은 verification-complete 이벤트를 발생시킵니다. 성공 이벤트에는 고유한 검증 세션 ID, 상태, 주소 등의 최소한의 결과 데이터가 포함됩니다.

<script>
  document.getElementById('wv')
    .addEventListener('verification-complete', (event) => {
      // event.detail 포함 내용:
      // id, status, flow, address, asset, blockchain
      console.log('Verification result:', event.detail);
    });
</script>

명칭	타입	설명
address	string	사용자의 지갑 주소
asset	string	토큰 티커(코인)
blockchain	string	블록체인(네트워크)
flow	string	검증 방법 및 플로우 (SIGNATURE_PROOF)
id	string	검증 세션의 고유 식별 ID
status	string	검증 결과 ("PENDING", "VERIFIED")

검증 실패 이벤트

검증이 실패하면 브라우저는 위젯 내에서 verification-error 이벤트를 발생시킵니다. 실패 이벤트에는 오류 코드와 메시지가 포함됩니다.

<script>
  document.getElementById('wv')
    .addEventListener('verification-error', (event) => {
      // event.detail 포함 내용: errorCode & message
      console.log('Verification error:', event.detail);
    });
</script>

명칭	타입	설명
errorCode	string	오류 코드
message	string	오류 메시지

errorCode: 오류 코드

GENERAL_API_ERROR: 응답 오류 (네트워크, API 실패 등)
CRYPTOGRAPHIC_SIGNATURE_FLOW_ERROR: 인증 취소 중 오류, 일반적으로 사용자가 프로세스를 취소할 때 발생합니다.

참고: 위젯은 기본적으로 대부분의 오류를 내부적으로 처리하도록 설계되어 있습니다. 오류가 발생하더라도 사용자는 일반적으로 현재 단계를 재시도하거나 검증 프로세스를 처음부터 다시 시작할 수 있습니다. 필요한 경우 오류 이벤트를 직접 처리하여 사용자 정의 로직을 적용하거나 대안적인 동작을 구현할 수 있습니다. 특히 GENERAL_API_ERROR가 발생한 경우 사용자에게 위젯을 새로 고침하거나 새로운 검증 세션을 시작하도록 안내하는 것을 권장합니다.

렌더 위젯

Vanilla JS 예시​

React 예시​

클라이언트 이벤트 처리

검증 성공 이벤트​

검증 실패 이벤트​

Vanilla JS 예시

React 예시

검증 성공 이벤트

검증 실패 이벤트