웹 앱 통합

이 페이지에서는 Unico 여정이 어떻게 작동하는지, 그리고 이를 애플리케이션에 통합하기 위해 사용할 수 있는 통합 모델을 설명합니다.

여정은 사용자가 신원 확인을 완료하기 위해 거치는 일련의 단계입니다. 예를 들어, 문서 사진 촬영과 얼굴 캡처(라이브니스) 수행 등이 있습니다.

Unico가 전체 경험을 관리합니다. 통합에 드는 노력은 최소화됩니다. 여정은 CreateProcess를 통해 생성되고, 사용자는 그곳으로 이동하며, 마지막에 결과를 받습니다. 그 사이에 일어나는 모든 것(화면, 안내, 검증)은 이미 구축되어 있으며 Unico가 유지 관리합니다.

통합 방식 선택

• Web SDK(unico-webframe 패키지): 백엔드가 이미 신원 확인 흐름을 제어하고 있고 클라이언트 측 캡처 컴포넌트만 필요한 경우에 사용합니다. base64 + 암호화된 JWT를 콜백으로 직접 반환하며, API 호출은 직접 관리합니다.
• Web App Integration(idpay-b2b-sdk 패키지): Unico가 전체 여정(다단계 흐름, 문서 캡처 + 라이브니스)을 오케스트레이션하기를 원하는 경우에 사용합니다. idpay-b2b-sdk 패키지는 내장형 Journeys SDK(iFrame) 모델을 구동합니다. 직접 접근(리다이렉트) 모델은 라이브러리가 필요하지 않습니다.

두 가지 통합 모델

고객마다 요구 사항이 다릅니다. Unico는 사용자를 여정으로 안내하기 위한 두 가지 모델을 제공합니다.

모델	적합한 경우
직접 접근	이미 WebView를 사용하는 모바일 애플리케이션, 또는 여정이 메인 페이지 외부에서 진행될 수 있는 웹 흐름
Journeys SDK	통합되고 매끄러운 경험이 필요하며 사용자를 동일한 환경 내에 유지하려는 웹 애플리케이션

직접 접근

사용자는 Unico가 호스팅하는 링크로 리다이렉트되어 그곳에서 여정이 진행됩니다. 완료되면 프로세스 생성 시 정의한 URL(callbackUri 매개변수)로 돌아갑니다.

이것은 도입하기 가장 간단한 방식입니다. 라이브러리 설치가 필요 없으며, 여정이 애플리케이션 자체 페이지 내에서 진행될 필요가 없을 때 적합합니다. 반면, 사용자를 고객의 환경 밖으로 데려가기 때문에 더 많은 마찰을 유발하고, 결과적으로 이탈률이 높아지는 경향이 있습니다.

프로세스를 생성하면 API 응답에 Unico가 호스팅하는 여정의 URL이 포함됩니다. 사용자를 그곳으로 안내하는 일반적인 방법은 두 가지입니다.

• 표준 리다이렉트. 사용자는 여정 URL로 직접 리다이렉트됩니다. 완료되면 Unico는 프로세스 생성 시 정의한 callbackUri로 사용자를 되돌려보냅니다.
• window.open()을 사용한 새 탭. 여정이 새 브라우저 탭에서 열려 사용자가 별도의 컨텍스트에 머무릅니다. 이 경우 callbackUri로의 URL 변경을 모니터링하고 프로세스가 완료되면 탭을 닫는 것이 좋습니다. API에 대한 자세한 내용은 MDN 문서를 참조하세요.

모바일 애플리케이션에서는 추가 리다이렉트 없이 여정을 직접 열기 위해 WebView를 사용하는 것이 일반적입니다. 이 경우 callbackUri는 딥링크도 허용하므로, 여정 완료를 계기로 네이티브 앱의 특정 화면을 열 수 있습니다. 딥링크를 반환 대상으로 구성하기만 하면 운영 체제가 사용자를 올바른 위치로 라우팅합니다.

Journeys SDK

여정은 애플리케이션 자체 내부에서 진행되며, 사용자를 자신의 컨텍스트 밖으로 내보내지 않습니다. Journeys SDK는 애플리케이션에 설치되어 필요할 때 여정을 여는 데 사용됩니다.

이는 더욱 통합되고 매끄러운 경험을 위한 권장 경로로, 사용자를 처음부터 끝까지 동일한 환경에 유지하여 흐름 전반에 걸쳐 마찰과 이탈을 줄이는 경향이 있습니다.

Unico는 최신 브라우저와 호환되는 JavaScript 라이브러리를 제공하며, 이를 통해 단 몇 줄의 코드로 거의 모든 애플리케이션에 여정을 통합할 수 있습니다.

호환성

이 라이브러리는 사용 중인 스택에 관계없이 마찰 없이 모든 프로젝트에 들어맞도록 설계되었습니다.

• 모든 웹 애플리케이션. UMD 형식으로 배포되어 최신 번들러(webpack 또는 Vite 등)를 통해 가져올 때 작동합니다. 모든 프레임워크(React, Angular, Vue) 또는 순수 JavaScript와 호환됩니다.
• 최신 브라우저. 라이브러리에는 Promises 및 async/await와 같은 기능에 필요한 폴리필이 이미 포함되어 있어, 이전 버전의 브라우저까지 호환성을 확장합니다.
• 표준 웹 API. 여정은 브라우저의 네이티브 기능을 기반으로 실행되며, 프로젝트 내 플러그인이나 외부 라이브러리에 의존하지 않습니다.

SDK의 내부 작동 방식

여정이 열리면 SDK는 페이지에 iFrame을 삽입하고 그 시점부터 전체 시각적 경험을 제어합니다. 각 단계의 화면, 스크립트, 에셋은 이 iFrame 내부에서 실행되며, 사용자가 시작하는 순간부터 프로세스가 완료될 때까지 이어집니다.

이러한 아키텍처 결정은 의도적인 것입니다. iFrame 격리는 Unico 여정이 애플리케이션의 스타일이나 동작에 간섭하지 않도록 보장합니다. 어떤 스크립트도 외부 컨텍스트로 새어 나가지 않으며, 어떤 CSS 규칙도 애플리케이션 자체 스타일과 충돌하지 않습니다. 그 결과 최종 사용자에게는 일관된 경험을, 고객의 제품에는 최소한의 영향을 제공합니다.

Unico가 iFrame의 생성과 관리를 책임지므로, 여정의 개선 사항(성능, 경험, 검증 등 무엇이든)은 통합된 애플리케이션을 변경할 필요 없이 모든 사용자에게 자동으로 제공됩니다. 통합은 항상 사용 가능한 최상의 최적화로 실행되며, 플랫폼의 모든 변화를 추적하거나 이에 대응할 필요가 없습니다.

시작하기

1단계: 설치

idpay-b2b-sdk 패키지는 IDPay 결제 여정과 신원 확인 여정 간에 공유됩니다. 신원 확인 사용 사례의 경우, 아래 단계에 표시된 대로 ByUnicoSDK 클래스를 가져옵니다.

  npm install idpay-b2b-sdk

Journeys SDK를 설치하는 권장 방법은 npm registry에서 제공되는 패키지에서 npm 또는 yarn과 같은 의존성 관리자를 통해 설치하는 것입니다. 설치와 의존성 관리를 단순화할 뿐만 아니라, 이 방식은 사용 중인 버전을 명확하게 제어할 수 있게 해 주며, 새 버전이 게시될 때마다 손쉽게 업데이트할 수 있습니다.

SDK는 **시맨틱 버저닝(SemVer)**을 따르며, 이는 patch 및 minor 업데이트가 호환성을 깨는 변경을 도입하지 않음을 의미합니다. 이러한 업데이트를 자동으로 수신하도록 프로젝트를 구성해도 안전합니다. 통합에 조정이 필요할 수 있는 변경은 major 버전으로 한정되며, 항상 마이그레이션 가이드가 함께 제공됩니다.

SDK를 최신 상태로 유지하세요

최신 버전을 유지하는 것은 두 가지 이유로 특히 중요합니다. 첫 번째는 보안입니다. 취약점이 발견되거나 통신 프로토콜을 강화할 기회가 생길 때마다 보안 패치가 게시됩니다. 오래된 버전을 실행한다는 것은 이러한 수정 사항을 놓치고 흐름을 불필요한 위험에 노출시키는 것을 의미합니다. 두 번째는 안정성입니다. 버그 수정도 같은 방식으로 배포되며, 오래된 버전에는 최신 릴리스에서 이미 해결된 동작이 남아 있을 수 있습니다.

시작하기 전에 Unico 지원팀에 도메인을 등록하세요. 모든 도메인은 HTTPS를 사용해야 합니다.

2단계: init(options) 호출

SDK를 초기화하고 여정이 올바르게 작동하는 데 필요한 스크립트를 미리 로드하여 최종 사용자에게 더 매끄러운 경험을 제공합니다. 흐름에서 가능한 한 일찍 호출하세요.

매개변수	필수	설명
token	예	Create Process API가 반환한 프로세스 토큰
env	아니요	테스트 환경에서만 'uat'로 설정

import { ByUnicoSDK } from 'idpay-b2b-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // 테스트 환경에서만
});

3단계: open(options) 호출

iFrame을 표시하고 사용자를 위해 여정을 시작합니다. 이 시점부터 모든 것이 iFrame 내부에서 자동으로 진행되며, 중간 단계를 관리할 필요가 없습니다.

매개변수	필수	설명
transactionId	예	Create Process API가 반환한 프로세스 ID
token	예	Create Process API가 반환한 프로세스 토큰
onFinish	예	여정이 종료되거나 닫힐 때 실행되는 콜백
onWidgetVisibilityChange	아니요	위젯의 표시 상태가 변경될 때 실행되는 콜백

애플리케이션과의 다음 상호작용은 사용자가 여정을 완료했든 닫았든 여정이 종료될 때 발생합니다. 그 시점에 SDK는 open에 매개변수로 전달된 onFinish 콜백을 호출합니다. 그로부터 애플리케이션은 getProcess API를 호출하여 결과를 확인하거나, 비동기 방식을 선호하는 경우 Webhook 알림을 기다릴 수 있습니다.

결과를 조회하는 것 외에도, onFinish를 사용하여 애플리케이션의 프런트엔드 상태를 처리하는 것이 좋습니다.

• 루프 방지. 여정이 종료된 직후 사용자가 흐름을 다시 트리거하는 경우 프로세스가 즉각적이고 불필요하게 다시 생성되는 것을 방지합니다.
• 흐름 관리. 여정이 닫힌 후 사용자가 출구 없는 화면에 갇히지 않도록, 애플리케이션의 다음 단계로 확실히 안내합니다.

경고

onFinish 콜백은 사용자가 여정을 완료했음을 알리지만, 승인을 보장하지는 않습니다. 프로세스는 Unico 검증 규칙 중 하나에서 실패로 종료되었을 수 있습니다. getProcess를 통한 조회 또는 Webhook 알림 수신은 선택 사항이 아닙니다. 이것이 실제 결과의 유일한 출처이며, 애플리케이션의 동작은 이를 기반으로 해야 합니다. 사용자가 승인되었는지 판단하기 위해 onFinish를 단독으로 사용해서는 안 됩니다.

onFinish 콜백은 여정이 어떻게 종료되었는지를 설명하는 객체를 받습니다.

필드	유형	설명
type	string	여정 종료 방식: 'FINISH'(완료) 또는 'CLOSE'(사용자가 완료 전 닫음)
transaction	object | undefined	type이 'FINISH'일 때 존재하며, type이 'CLOSE'일 때는 undefined
transaction.id	string	프로세스 식별자(전달된 transactionId와 동일)
transaction.redirectUrl	string	여정 후 사용자를 리다이렉트할 URL

onWidgetVisibilityChange 콜백 처리는 선택 사항이며, 사용 사례에 따라 관련이 없을 수 있습니다. 이 콜백은 위젯의 표시 상태가 변경될 때마다 호출되며, 특정 시나리오에서만 유용합니다. 일부 여정은 투명한 배경을 표시하여 경험 뒤로 애플리케이션 페이지가 보이게 합니다. 검증 흐름 중에 자체 모달을 표시하는 애플리케이션(예: 여러 KYC 공급자 간 오케스트레이션의 일부)은 해당 모달이 Unico 위젯 뒤에 표시되어 시각적 경험을 저하시킬 수 있습니다. 이 경우 콜백을 사용하면 Unico 여정이 활성화된 동안 추가 시각 요소를 숨기고 종료 후 복원할 수 있습니다. 위젯과 겹칠 수 있는 UI가 애플리케이션에 없다면 안전하게 생략할 수 있습니다.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // 여정 완료(transaction = { id, redirectUrl }): 여기서 자체 흐름을 계속하세요.
    }
    // type === 'CLOSE' → 사용자가 완료 전에 닫음;
  },
  // 선택 사항: 앱이 위젯과 겹칠 수 있는 UI를 표시하는 경우에만 필요합니다.
  onWidgetVisibilityChange: (visible) => {
    // 위젯 표시 상태에 따라 모달을 숨기거나 복원하세요
  },
});

// 언제든지 SDK를 명시적으로 닫으려면:
ByUnicoSDK.close();

아래 시퀀스 다이어그램은 SDK와 API 결과를 사용하여 iFrame을 구성하는 방법을 보여줍니다.

보안

이 섹션의 범위

이 보안 근거는 특히 Web App Integration(idpay-b2b-sdk)에 적용됩니다. Web SDK(unico-webframe)는 다른 모델을 사용하며, 전적으로 페이지 컨텍스트에서 실행되고 CSP가 필요합니다. 이 둘은 서로 다른 보안 아키텍처를 가진 별개의 제품입니다.

이 모델의 보안은 SDK와 iFrame 내부에서 실행되는 애플리케이션 간의 통신 프로토콜을 시작으로 계층적으로 구축됩니다.

여정이 로드되면 양측은 통신을 수립하기 위해 핸드셰이크를 수행합니다. 이 과정에서 Unico 애플리케이션은 postMessage를 통해 수신한 데이터 주입 메시지의 출처를, 환경(UAT 및 PROD)별로 구분된 승인된 도메인의 폐쇄 목록과 대조하여 검증합니다. 승인되지 않은 출처의 메시지는 즉시 폐기되어, 여정이 승인되지 않은 페이지에 삽입되는 것을 방지하고 클릭재킹과 같은 취약점에 대한 공격 표면을 제거합니다.

출처 검증 외에도, 흐름은 유효한 트랜잭션 토큰(Unico 백엔드가 발급하고 서명한 일회용 JWT)이 있을 때만 진행됩니다. 이를 통해 승인된 출처라도 만료되거나 재사용되거나 위조된 토큰으로는 작동할 수 없도록 보장합니다.

핸드셰이크 후 토큰은 iFrame에 주입되며, 이후 양측 간에 민감한 정보는 더 이상 오가지 않습니다. 나머지 모든 통신은 인터페이스 제어(열기, 닫기, 화면 전환)에만 사용되어, 여정 중 프로세스 데이터가 가로채이거나 유출되는 것을 방지합니다.

iFrame 격리는 런타임에서 Unico 스크립트의 무결성도 보호합니다. 코드는 페이지와 분리된 컨텍스트에서 실행되므로 외부 스크립트가 접근하거나 수정할 수 없으며, 이를 통해 여정이 구축된 그대로 간섭 없이 실행되도록 보장합니다.

설계상 이 통합 모델에서는 CSP를 채택하지 않습니다. 승인된 도메인은 각 고객의 보안 구성의 일부이며, 이를 헤더에 공개하면 악의적인 행위자가 인프라를 매핑하기 쉬워질 수 있습니다. 고객 식별은 init 시점에만 이루어지므로, 그 전에 이러한 도메인을 헤더에 동적으로 주입하는 것은 불가능하며, 따라서 이 기밀성을 포기하지 않고는 CSP를 적용할 수 없습니다. 모든 보안 보장은 위에서 설명한 핸드셰이크 프로토콜로 제공됩니다.

SDK 관련 문제 해결

이 섹션에서는 통합 중에 흔히 발생하는 문제와 이를 조사하기 위한 권장 방법을 다룹니다.

예기치 않은 동작 또는 흐름 중단

애플리케이션의 스크립트가 DOM에서 iFrame을 직접 조작하고 있지 않은지 확인하세요. SDK는 페이지의 body에서 iFrame을 생성하고 관리하며, 범위, 위치 지정, 속성 등에 대한 외부의 수정은 여정의 수명 주기에 간섭하여 예측할 수 없는 동작을 유발할 수 있습니다.

예상과 다른 시각적 경험

애플리케이션의 전역 스타일시트가 iFrame 내부의 속성을 덮어쓰고 있지 않은지 확인하세요. SDK는 iFrame과 그 모든 내부 요소를 동적 ID와 unico 접두사가 붙은 클래스로 생성하므로, ID 또는 클래스 선택자로 인한 충돌 위험이 크게 줄어듭니다. 그럼에도 불구하고 범위가 넓은 CSS 규칙(예: 태그 선택자)은 iFrame 내부 요소에 도달하여 사용자에게 제공되는 시각적 경험을 변경할 수 있습니다.

SDK 라이브러리 파일이 직접 수정됨

라이브러리 파일이 의존성 관리자 외부에서 수정되지 않았는지 확인하세요. 라이브러리는 npm 또는 yarn으로만 관리해야 하며, 설치된 파일을 직접 편집해서는 안 됩니다. 수동 수정은 재현하기 어려운 비정상적인 동작을 유발할 수 있으며 Unico 지원의 지원을 불가능하게 만듭니다.

캡처 테스트 중에는 DevTools를 열어 두지 마세요

Unico 애플리케이션은 얼굴 캡처에 Capture SDK(unico-webframe)를 사용하며, 열려 있는 DevTools를 잠재적 사기 신호로 감지하여 제출을 차단합니다. 엔드 투 엔드 캡처 테스트를 실행하기 전에 DevTools를 닫으세요.

지원되지 않는 통합

이 문서에 설명된 모델(직접 접근 및 Journeys SDK)은 Unico가 공식적으로 지원하는 유일한 통합 방식입니다. 이러한 표준에서 벗어난 통합은 예기치 않은 동작, 보안 흐름 오류, 여정 중단을 유발할 수 있으며 Unico 지원의 적용을 받지 못합니다.

지원되지 않는 방식의 몇 가지 예:

• 모바일 애플리케이션에서 SDK를 WebView 내부에 임베드하는 것. 이러한 경우 올바른 방식은 직접 접근 모델을 사용하여 Journeys SDK를 거치지 않고 여정 링크를 WebView에서 직접 여는 것입니다.
• Journeys SDK를 거치지 않고 HTML <iframe> 태그로 iFrame을 직접 로드하는 것. iFrame은 SDK의 내부 구현 세부 사항이며 수동으로 인스턴스화해서는 안 됩니다. 올바른 방식은 iFrame 수명 주기를 안전하게, 기대되는 표준 범위 내에서 관리하는 Journeys SDK를 사용하는 것입니다.

어떤 방식이 지원되는 표준 범위 내에 있는지 의문이 있는 경우, 구현을 진행하기 전에 문서를 참조하거나 지원팀에 문의하세요.