웹 앱 통합
이 페이지에서는 Unico 여정이 어떻게 작동하는지와 애플리케이션에 임베드하기 위해 사용 가능한 통합 모델에 대해 설명합니다.
여정은 사용자가 신원 확인을 완료하기 위해 거치는 일련의 단계입니다. 예를 들어: 문서 사진을 촬영하고 안면 캡처(라이브니스)를 수행하는 것입니다.
Unico가 전체 경험을 관리합니다. 통합 노력은 최소한입니다: 여정은 CreateProcess를 통해 생성되고, 사용자는 해당 여정으로 안내되며, 결과는 마지막에 수신됩니다. 그 사이의 모든 것 — 화면, 지침, 검증 — 은 이 미 Unico에 의해 구축되고 유지 관리됩니다.
두 가지 통합 모델
각 고객은 서로 다른 요구 사항이 있습니다. Unico는 사용자를 여정으로 안내하기 위한 두 가지 모델을 제공합니다.
| 모델 | 최적 대상 |
|---|---|
| 직접 액세스 | 이미 WebView를 사용하는 모바일 애플리케이션, 또는 메인 페이지 외부에서 여정이 발생할 수 있는 웹 흐름 |
| Journeys SDK | 동일한 환경 내에서 사용자를 유지하면서 통합된 원활한 경험이 필요한 웹 애플리케이션 |
- 직접 액세스
- Journeys SDK
사용자는 Unico에서 호스팅하는 링크로 리다이렉트되며, 여기서 여정이 진행됩니다. 완료 시
프로세스 생성 중에 정의된 URL(callbackUri 매개변수)로 반환됩니다.
이것은 가장 간단한 도입 방식입니다: 라이브러리 설치가 필요 없으며, 여정이 애플리케이션 자체의 페이지 내에서 발생할 필요가 없을 때 잘 작동합니다. 반면, 사용자를 고객의 환경 밖으로 내보내는 것은 더 많은 마찰을 야기하고, 결과적으로 더 높은 이탈률을 초래하는 경향이 있습니다.
프로세스를 생성한 후, API 응답에는 Unico가 호스팅하는 여정의 URL이 포함됩니다. 사용자를 안내하는 두 가지 일반적인 방법이 있습니다:
- 표준 리다이렉트. 사용자는 여정 URL로 직접 리다이렉트됩니다. 완료 시
Unico는 프로세스 생성 중에 정의된
callbackUri로 다시 리다이렉트합니다. window.open()으로 새 탭. 여정이 새 브라우저 탭에서 열리며, 사용자를 별도의 컨텍스트에 유지합니다. 이 경우,callbackUri로의 URL 변경을 모니터링하고 프로세스가 완료되면 탭을 닫는 것이 권장됩니다. API에 대한 자세한 내용은 MDN 문서를 참조하세요.
모바일 애플리케이션에서는 추가 리다이렉트 없이 여정을 직접 열기 위해 WebView를 사용하는 것이
일반적입니다. 이 경우 callbackUri는 딥링크도 허용하며, 여정의 완료로 네이티브 애플리케이션의
특정 화면을 열 수 있습니다. 딥링크를 반환 목적지로 구성하기만 하면 운영 체제가 사용자를
올바른 위치로 라우팅합니다.
여정은 사용자를 컨텍스트에서 벗어나게 하지 않고 애플리케이션 자체 내에서 진행됩니다. Journeys SDK가 애플리케이션에 설치되어 필요할 때 여정을 여는 데 사용됩니다.
이것은 더 통합되고 원활한 경험을 위한 권장 경로로, 사용자를 동일한 환경에 유지하여 흐름 전반에 걸쳐 마찰과 이탈을 줄이는 경향이 있습니다.
Unico는 최신 브라우저와 호환되는 JavaScript 라이브러리를 제공하며, 단 몇 줄의 코드로 거의 모든 애플리케이션에 여정을 통합할 수 있습니다.
호환성
이 라이브러리는 사용 중인 스택에 관계없이 모든 프로젝트에 마찰 없이 적합하도록 설계되었습니다:
- 모든 웹 애플리케이션. UMD 형식으로 배포되며, 최신 번들러(webpack이나 Vite 등)를 통해 가져올 때 작동합니다. 모든 프레임워크(React, Angular, Vue) 또는 순수 JavaScript와 호환됩니다.
- 최신 브라우저. 라이브러리에는 Promises와
async/await같은 기능에 필요한 polyfill이 이미 포함되어 있어, 이전 브라우저 버전으로의 호환성도 확장됩니다. - 표준 웹 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는 **Semantic Versioning (SemVer)**을 따르므로, 패치 및 마이너 업데이트는 파괴적 변경을 도입하지 않습니다. 프로젝트가 이러한 업데이트를 자동으로 수신하도록 구성하는 것이 안전합니다. 통합 업데이트가 필요할 수 있는 변경은 메이저 버전에 예약되며, 항상 마이그레이션 가이드가 함께 제공됩니다.
최신 버전을 유지하는 것은 두 가지 이유로 특히 중요합니다. 첫 번째는 보안입니다: 취약점이 식별되거나 통신 프로토콜을 강화할 기회가 발생할 때마다 보안 패치가 게시됩니다. 오래된 버전을 실행하면 이러한 수정 사항을 놓치고 흐름을 불필요한 위험에 노출시킵니다. 두 번째는 안정성입니다: 버그 수정은 같은 방식으로 배포되며, 이전 버전은 최신 릴리스에서 이미 해결된 동작을 보일 수 있습니다.
시작하기 전에, Unico 지원 팀에 도메인을 등록하세요. 모든 도메인은 HTTPS를 사용해야 합니다.
2단계 — CSP 및 Permissions-Policy 구성
페이지가 이미 Content-Security-Policy 또는 Permissions-Policy 헤더를 전송하는 경우, SDK의 iFrame, 스크립트 및 카메라 접근이 올바르게 작동하도록 다음 지시문을 추가하세요.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
페이지가 CSP 또는 Permissions-Policy 헤더를 전송하지 않는 경우 이 단계를 건너뛸 수 있습니다 — 브라우저는 기본적으로 제한을 적용하지 않습니다.
3단계 — init(options) 호출
SDK를 초기화하고 여정이 올바르게 작동하는 데 필요한 스크립트를 사전 로드하여, 최종 사용자에게 더 원활한 경험을 제공합니다. 흐름에서 가능한 한 일찍 호출하세요.
| 매개변수 | 필수 | 설명 |
|---|---|---|
token | 예 | Create Process API에서 반환된 프로세스 토큰 |
env | 아니오 | 테스트 환경에서만 'uat'로 설정 |
import { ByUnicoSDK } from 'idpay-b2b-sdk';
ByUnicoSDK.init({
token,
// env: 'uat' // only for test environments
});
4단계 — 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') {
// Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
}
// type === 'CLOSE' → user closed before finishing;
},
// Optional: only needed if your app shows UI that could overlap the widget.
onWidgetVisibilityChange: (visible) => {
// suppress or restore your modal based on widget visibility
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
아래 시퀀스 다이어그램은 SDK와 API 결과를 사용하여 iFrame을 구성하는 방법을 보여줍니다:
샘플 앱
| 언어 / 프레임워크 | 설명 | 리포지토리 |
|---|---|---|
| Angular | Journeys SDK를 구현한 Angular PoC | GitHub — unico-cbu-poc-angular |
| JS Vanilla | Journeys SDK를 구현한 JS Vanilla PoC | GitHub — unico-cbu-poc-js |
| React | Journeys SDK를 구현한 React PoC | GitHub — unico-cbu-poc-react |
| Vue JS | Journeys SDK를 구현한 Vue JS PoC | GitHub — unico-cbu-poc-vuejs |
보안
이 모델의 보안은 SDK와 iFrame 내에서 실행되는 애플리케이션 간의 통신 프로토콜부터 시작하여 레이어로 구축됩니다.
여정이 로드되면, 양측은 통신을 수립하기 위해 핸드셰이크를 수행합니다. 이 과정에서 Unico
애플리케이션은 postMessage를 통해 수신된 데이터 주입 메시지의 출처를 환경(UAT 및 PROD)별로
분류된 승인된 도메인의 폐쇄 목록에 대해 검증합니다. 승인되지 않은 출처의 메시지는 즉시
폐기되어, 여정이 무단 페이지에 임베드되는 것을 방지하고 클릭재킹 등의 취약점에 대한
공격 표면을 제거합니다.
출처 검증 외에도, 흐름은 유효한 트랜잭션 토큰으로만 진행됩니다: Unico 백엔드에서 발급되고 서명된 일회용 JWT입니다. 이를 통해 승인된 출처라도 만료되었거나, 재사용되었거나, 위조된 토큰으로는 작동할 수 없습니다.
핸드셰이크 후, 토큰은 iFrame에 주입되며 양측 간에 민감한 정보는 흐르지 않습니다. 나머지 모든 통신은 인터페이스 제어 — 열기, 닫기, 화면 전환 — 에만 사용되어, 여정 중 프로세스 데이터가 가로채지거나 유출되는 것을 방지합니다.
iFrame 격리는 런타임에서 Unico 스크립트의 무결성도 보호합니다. 코드가 페이지와 분리된 컨텍스트에서 실행되므로, 외부 스크립트에 의해 접근되거나 수정될 수 없어, 여정이 구축된 그대로 간섭 없이 정확하게 실행됩니다.
CSP 및 Permissions-Policy
페이지가 Content-Security-Policy 또는 Permissions-Policy 헤더를 전송하는 경우, SDK의 iFrame, 스크립트 및 카메라 접근이 올바르게 작동하도록 다음 지시문이 있는지 확인하세요.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
페이지가 이러한 헤더를 전송하지 않는 경우, 브라우저는 기본적으로 제한을 적용하지 않으며 별도의 구성이 필요하지 않습니다.
SDK 관련 문제 해결
이 섹션에서는 통합 중에 발생하는 가장 일반적인 문제와 이를 조사하기 위한 권장 방법을 다룹니다.
예상치 못한 동작 또는 중단된 흐름
애플리케이션 스크립트가 DOM에서 iFrame을 직접 조작하고 있는지 확인하세요. SDK는 페이지
body에 iFrame을 생성하고 관리하며, 범위, 위치 지정 또는 속성에 대한 외부 수정은 여정의
수명 주기를 방해하고 예측할 수 없는 동작을 일으킬 수 있습니다.
예상과 다른 시각적 경험
애플리케이션의 전역 스타일시트가 iFrame 내부의 속성을 재정의하고 있는지 확인하세요.
SDK는 동적 ID와 unico 접두사가 붙은 클래스로 iFrame과 모든 내부 요소를 생성하여, 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를 거치지 않고
<iframe>HTML 태그를 통해 직접 iFrame을 로드하는 것. iFrame은 SDK의 내부 구현 세부 사항이며 수동으로 인스턴스화해서는 안 됩니다. 올바른 접근 방식은 Journeys SDK를 사용하는 것으로, iFrame 수명 주기를 안전하게 예상되는 표준 내에서 관리합니다.
접근 방식이 지원되는 표준 내에 있는지 의문이 있다면, 구현을 진행하기 전에 문서를 참조하거나 지원팀에 문의하세요.