메인 콘텐츠로 건너뛰기
iframe을 사용해 Didit 인증 흐름을 애플리케이션 안에 직접 삽입하세요. 사용자를 사이트 밖으로 리디렉션하지 않으므로 끊김 없는 경험을 제공합니다.

개요


시작하는 가장 빠른 방법입니다. UniLink URL을 복사해 붙여넣기만 하면 됩니다.

필요한 것

  1. Didit 워크플로(Didit 콘솔에서 생성)
  2. UniLink URL(워크플로에서 Copy Link 클릭)

구현

⚠️ 필수: 라이브니스 감지 중 카메라에 접근하려면 allow 속성이 반드시 필요합니다.

주요 이점

  • 1분 미만 설정: 백엔드도, API 키도 필요 없습니다
  • 설정 불필요: 콜백 URL은 워크플로 설정에서 지정됩니다
  • MVP에 적합: 바로 시작할 수 있습니다

API 세션 iframe(백엔드 필요)

세션별 맞춤 설정이 필요한 고급 연동을 위한 방식입니다.

사용 시기

  • 세션마다 사용자 지정 vendor_data 또는 metadata를 전달
  • 세션마다 다른 콜백 URL 설정
  • 인증이 시작되기 전에 서버에서 세션 추적
  • 세션을 사용자 ID와 연결

구현

1단계: 세션 생성(백엔드) 세션 생성 응답에는 url이라는 필드가 있습니다. 이 값을 iframe의 src로 사용하세요.
2단계: iframe에 삽입(프런트엔드)

이벤트 수신(postMessage)

인증 페이지는 이벤트를 부모 창으로 전송합니다. 모든 메시지는 다음 구조를 가집니다:
payload는 중첩되어 있습니다. event.data.sessionId가 아니라 event.data.data.sessionId를 읽으세요:
주요 이벤트는 다음과 같습니다: didit:ready({ sessionId }), didit:started, didit:step_started / didit:step_completed / didit:step_changed({ step, ... }), didit:status_updated({ status }), didit:completed({ sessionId, status }), didit:cancelled, didit:error({ error, step? }), didit:close_request, 그리고 didit:layout({ contentHeight, colorScheme, dir }, 아래 참조). JavaScript SDK 이벤트 참조에는 타입이 지정된 콜백으로 제공되는 인증 이벤트가 나열되어 있습니다. 버전 0.5.0부터 SDK는 레이아웃 메시지를 onEvent로 전달하지 않고 내부에서 처리합니다.

didit:layout으로 iframe 크기 조정

인증 페이지는 didit:layout 메시지로 필요한 공간의 크기를 알려줍니다. 페이지가 로드될 때 한 번, 그리고 콘텐츠 높이, 테마 또는 텍스트 방향이 바뀔 때마다 다시 전송합니다:
자체 iframe에서 didit:layout을 받으려면 iframe의 인증 URL에 sdk_presentation=embedded를 추가하세요. 버전 0.5.0부터 JavaScript SDK가 이 프레젠테이션을 자동으로 설정합니다. 프레젠테이션 파라미터가 없으면 페이지는 독립형 레이아웃을 사용하며 레이아웃 메시지를 보내지 않습니다.
이 호스트는 권장 크기를 따릅니다. 너비 1024px 이상에서는 고정 카드, 540px 이하에서는 전체 화면, 그 사이에서는 너비 500px의 iframe이 페이지가 보고하는 높이를 사용합니다:
541px에서 1023px 사이에서는 이 예시가 레이아웃 메시지가 도착하기 전까지 초기 높이 700px를 사용하며, 보이는 창 높이의 90%를 넘지 않도록 제한합니다. 데스크톱과 휴대폰 크기는 즉시 적용됩니다. 휴대폰에서는 iframe이 창 전체를 덮으므로, 호스트에서 인증을 벗어날 수 있는 방법을 제공하세요. iframe 주변에 배치하는 컨트롤은 colorScheme과 dir을 사용해 페이지의 테마와 텍스트 방향에 맞추세요. 사용자의 연결이 끊기면 페이지에 “No internet connection” 화면이 표시되며, 연결이 복구되면 자동으로 닫힙니다. 사용자가 이 화면에서 Exit Verification을 선택하면 페이지는 error: "network_error"를 담은 didit:error를 보낸 뒤 didit:cancelled를 보냅니다. didit:cancelled를 받으면 iframe을 닫으세요.

모달 구현

페이지 위에 겹쳐 표시되는 세련된 모달 경험을 위한 방법입니다:

HTML/CSS/JS


React 컴포넌트

모달 기반 인증을 위한 재사용 가능한 React 컴포넌트입니다:

사용법


Vue 컴포넌트


구성

필수 권한

캡처, 위치, 복사, 미디어 호환성에 사용하는 전체 권한 목록은 다음과 같습니다:
allow 속성은 권한을 위임하지만, 사용자의 선택이나 호스트 페이지의 더 엄격한 Permissions-Policy 헤더를 무시하지는 않습니다.

iframe 크기

인증 흐름은 자신이 놓인 iframe의 크기에 맞춰 배치됩니다. 표시될 창에 맞게 iframe 크기를 설정하세요: 중간 범위에서는 첫 didit:layout 메시지가 도착하기 전까지 500px × 700px로 시작하며, 높이 상한은 동일하게 적용합니다. didit:layout 예제는 메시지가 도착하기 전이라도 컴퓨터와 휴대폰 크기를 포함해 세 가지 크기를 모두 적용합니다.

콘텐츠 보안 정책(CSP)

CSP를 사용하는 경우 frame-src 지시어에 Didit 도메인을 추가하세요:

기기 간 인증

InContext iframe은 기기 간 인증을 자동으로 지원합니다:
  1. 사용자가 데스크톱에서 인증을 시작합니다
  2. 카메라를 사용할 수 없으면 QR 코드가 표시됩니다
  3. 사용자가 모바일에서 QR 코드를 스캔합니다
  4. 사용자가 모바일에서 인증을 완료합니다
  5. 데스크톱 iframe에 결과가 자동으로 업데이트됩니다
이 과정은 자동으로 진행되며, 별도의 설정은 필요하지 않습니다.

문제 해결

카메라가 작동하지 않음

  1. iframe에 전체 권한 목록이 포함되어 있는지 확인하세요
  2. 사이트가 HTTPS로 제공되는지 확인하세요
  3. 사용자가 도메인에 카메라 권한을 허용했는지 확인하세요
  4. iframe에서 카메라 접근이 실패하면 리디렉션 방식을 사용해 보세요

iframe이 로드되지 않음

  1. 콘텐츠 보안 정책(CSP) 문제가 있는지 확인하세요
  2. frame-src 지시어에 https://verify.didit.me를 추가하세요
  3. 브라우저 콘솔에서 오류를 확인하세요

postMessage 메시지가 수신되지 않음

  1. 올바른 출처(https://verify.didit.me 또는 화이트 라벨 도메인)에서 오는 메시지를 수신하도록 리스닝하고 있는지 확인하세요
  2. iframe을 열기 전에 이벤트 리스너를 추가했는지 확인하세요
  3. 이벤트 이름과 형식을 확인하세요. 타입에는 접두사가 붙고(verification_complete가 아니라 didit:completed), 페이로드는 event.data.data 안에 중첩되어 있습니다

예제 저장소

GitHub 저장소

GitHub에서 소스 코드와 예제를 확인하세요

마지막 수정일 2026년 11월 7일