문서/인증 창

인증 창 연결하기

팝업, 완료 알림, 모바일·QR 전환 설정

인증 창 구성#

sendwich 인증 창은 https://id.it.kr에서 제공하며, 생성 응답의 verification_url로 엽니다. PC의 QR 코드, 모바일 문자 앱 연결, 남은 시간과 완료·취소·만료 화면을 지원합니다.

팝업·복귀 주소 등록#

프로젝트 설정의 인증 창 연결 설정 · 선택에서 서비스의 주소를 등록합니다.

설정	용도	등록 예시
허용 도메인	팝업 완료 알림을 받을 부모 페이지의 출처	`https://shop.example.com`
인증 후 돌아갈 URL	같은 탭에서 인증한 뒤 돌아갈 페이지	`https://shop.example.com/verification/return`

허용 도메인은 경로 없이 스킴·호스트·포트로 구성합니다. 복귀 URL은 경로까지 정확히 등록합니다. 실제 SMS 프로젝트에는 HTTPS가 필요하며, 와일드카드와 #은 허용하지 않습니다.

인증 생성 시 사용할 주소를 parent_origin, return_url로 전달합니다. 두 필드는 선택 사항이며, 프로젝트에 등록한 값과 일치해야 합니다.

json

{
  "mode": "discover",
  "client_reference": "attempt_93a7",
  "state": "SERVER_GENERATED_RANDOM_STATE",
  "parent_origin": "https://shop.example.com",
  "return_url": "https://shop.example.com/verification/return"
}

팝업 열기#

사용자 클릭 이벤트에서 빈 창을 먼저 열고, 인증 생성 응답을 받은 뒤 해당 창으로 이동합니다. /api/phone-verifications는 서비스 서버에 구현할 경로입니다. 서버는 사용자와 인증 ID를 연결해 저장하고, 화면에 필요한 값을 반환합니다.

javascript

async function startVerification() {
  const popup = window.open('', 'veri', 'popup,width=460,height=760');
  try {
    const response = await fetch('/api/phone-verifications', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ attempt: crypto.randomUUID() })
    });
    if (!response.ok) throw new Error('인증을 시작하지 못했어요.');
    const session = await response.json();
    // 아래의 메시지 핸들러를 먼저 설치한 뒤 창을 이동해요.
    watchVerification(popup, session);
    if (popup) popup.location.href = session.verification_url;
    else window.location.assign(session.verification_url);
  } catch (error) {
    popup?.close();
    throw error;
  }
}

완료 알림#

parent_origin을 지정하면 인증 창이 부모 페이지에 다음 형식의 postMessage를 전송합니다.

json

{
  "type": "veri.verification.result",
  "id": "vrf_EXAMPLE",
  "status": "verified",
  "state": "SERVER_GENERATED_RANDOM_STATE"
}

출처, 팝업 핸들, 인증 ID, state가 일치하는 알림을 받으면 서버에서 결과를 조회합니다. 예제의 refreshResultFromYourServer는 서비스 서버에서 결과를 가져오는 함수입니다.

javascript

function watchVerification(popup, session) {
  if (!popup) return;
  const handler = async (event) => {
    if (event.origin !== 'https://id.it.kr' || event.source !== popup) return;
    const data = event.data;
    if (data?.type !== 'veri.verification.result' ||
        data.id !== session.id || data.state !== session.state) return;
    window.removeEventListener('message', handler);
    await refreshResultFromYourServer(session.id);
  };
  window.addEventListener('message', handler);
  // 페이지를 떠나거나 인증이 만료되면 핸들러도 제거해요.
  return () => window.removeEventListener('message', handler);
}

모바일과 QR#

모바일에서는 문자 앱을 열어 사용자가 직접 전송합니다. 본문 자동 입력을 지원하지 않는 기기를 위해 번호와 문자 복사 기능을 제공합니다. PC의 QR 코드로 휴대폰에서 열어도 동일한 인증 세션을 사용합니다.

부모 창이 없으면 완료 화면의 버튼으로 등록된 복귀 URL에 이동합니다. URL에는 verification_id와 state가 쿼리로 추가됩니다. 복귀한 페이지는 이 값을 서버에 저장한 시도와 대조하고, API 조회나 웹훅으로 최종 결과를 확인합니다.