웹 앱 통합

이 페이지에서는 웹 및 SDK 계약을 위한 두 가지 클라이언트 측 통합 방법을 다룹니다: 사용자를 Unico 호스팅 여정으로 리다이렉트하는 방법과 iFrame SDK를 통해 여정을 임베드하는 방법입니다.

사용자 리다이렉트

프로세스를 생성하면 응답에 Unico 호스팅 여정을 가리키는 URL이 포함됩니다. 이 URL을 사용하여 사용자를 캡처 경험으로 안내하세요. 이 전환을 관리하는 두 가지 방법이 있습니다:

1. 표준 리다이렉트

사용자를 여정 URL로 직접 리다이렉트합니다. 사용자가 프로세스를 완료하면 Unico는 프로세스 생성 시 지정한 URL로 사용자를 다시 리다이렉트합니다.

2. window.open()을 사용한 새 탭

사용자가 별도의 컨텍스트에 있을 수 있도록 새 브라우저 탭에서 여정을 엽니다. 반환 URL로의 URL 변경을 모니터링하고 프로세스가 완료되면 탭을 닫으세요.

window.open() API에 대한 자세한 내용은 MDN 문서를 참조하세요.

iFrame

경고

이 문서의 표준을 따르지 않는 통합은 예상치 못한 중단을 유발할 수 있으며 Unico 지원의 적용 범위에 포함되지 않습니다.

지원되지 않는 방법의 예: WebView 내에 SDK를 임베드하거나 HTML 태그를 통해 직접 iFrame을 로드하는 경우.

시작 방법

1단계 — 설치

by Unico SDK는 IDPay와 동일한 패키지를 사용합니다:

npm install idpay-b2b-sdk

팁

특정 버전을 고정하지 않고 설치하면 패키지 관리자가 항상 최신 마이너 및 패치 릴리스를 자동으로 가져옵니다.

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

2단계 — init(options) 호출

SDK를 초기화하고 에셋을 사전 로드하여 최종 사용자에게 더 매끄러운 경험을 제공합니다. 흐름에서 가능한 한 빨리 이 함수를 호출하세요.

매개변수	필수 여부	설명
type	예	by Unico 흐름의 경우 'IFRAME'으로 설정
token	예	프로세스 생성 API가 반환한 프로세스 토큰
env	아니요	테스트 환경에서만 'uat'으로 설정

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

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

3단계 — open(options) 호출

사전 로드된 iFrame을 표시하고 페이지와 Unico 여정 간의 메시지 흐름을 시작합니다.

매개변수	필수 여부	설명
transactionId	예	프로세스 생성 API가 반환한 프로세스 ID
token	예	프로세스 생성 API가 반환한 프로세스 토큰
onFinish	예	여정이 종료되거나 닫힐 때 실행되는 콜백

onFinish 콜백은 트랜잭션 ID, 리다이렉트 URL 및 완료 유형이 포함된 프로세스 객체를 수신합니다.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

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

보안

CSP 대신 인증 토큰이 있는 iFrame 솔루션 선택

신중한 분석 끝에 선택된 방법은 Content Security Policy(CSP) 구현 대신 인증 토큰이 있는 iFrame을 사용합니다. 이 결정은 보안 요구 사항과 클라이언트 요구를 충족하는 데 필요한 유연성에 의해 동기 부여되었습니다.

CSP의 컨텍스트 및 문제점

Content Security Policy는 XSS 및 코드 주입 공격으로부터 웹 애플리케이션을 보호하는 강력한 도구입니다. 그러나 CSP 정책을 구성하려면 신뢰할 수 있는 도메인의 엄격한 목록을 정의해야 합니다. 이 방법은 도메인이 고정되고 예측 가능한 경우에 효과적이지만, 동적이고 가변적인 도메인을 사용하는 클라이언트의 경우 이 엄격한 구성이 상당한 문제를 야기합니다.

동적 도메인의 취약점

동적 도메인은 CSP를 사용할 때 상당한 보안 위험을 초래합니다. 클라이언트가 자주 변경되거나 동적으로 생성되는 도메인을 가진 경우 CSP 정책을 새 도메인을 포함하도록 지속적으로 업데이트해야 합니다. 이는 유지 관리 부담을 증가시킬 뿐만 아니라 적절하게 관리되지 않으면 정책에 나열된 모든 도메인이 잠재적인 공격 표면으로 노출됩니다.

iFrame 및 인증 토큰을 이용한 솔루션

이러한 위험을 완화하고 클라이언트가 요구하는 유연성을 충족하기 위해 선택된 솔루션은 iFrame과 인증 토큰을 결합하여 정적 도메인 목록 없이 추가적인 보안 레이어를 제공합니다.

작동 방식:

• 안전한 인증 — 각 iFrame은 트랜잭션별로 고유한 인증 토큰과 함께 로드되어 권한이 있는 사용자만 콘텐츠에 접근할 수 있도록 합니다. 토큰은 실시간으로 검증됩니다.
• 콘텐츠 격리 — iFrame은 별도의 브라우징 컨텍스트에서 실행되어 서로 다른 출처 간의 간섭 위험을 줄이고 잠재적인 공격을 완화합니다.
• 동적 도메인에 대한 유연성 — 정적 CSP 정책에 의존하지 않으므로 솔루션이 지속적인 정책 업데이트 없이 동적 클라이언트 도메인에 적응합니다.