---
title: SDK
description: '웹용 Unico SDK를 구현하는 방법: 설치, init/open 메서드, 전체 화면 가이드, iFrame + 인증 토큰 보안 모델.'
canonical: https://developer.unico.io/ko/dual-api/developers/regional-solutions/card-not-present-verification/integration/controlling-the-experience/web/sdk
locale: ko
generated_by: markdown-export
---

- [/ko/](/ko/)
- 지역별 솔루션
- [비대면 카드 검증](/ko/dual-api/developers/regional-solutions/card-not-present-verification)
- [통합](/ko/dual-api/developers/regional-solutions/card-not-present-verification/integration/overview)
- [경험 제어](/ko/dual-api/developers/regional-solutions/card-not-present-verification/integration/controlling-the-experience/overview)
- Web
- SDK

**이 페이지에서# SDK

웹 사용의 경우, 다음과 같은 이유로 Unico SDK를 사용하는 것이 권장되는 방식입니다:

더 높은 보안성;
귀사의 흐름과 통합된 경험;
SDK 사용 시 더 높은 전환율;
더 쉬운 구현.

경고이 문서에서 정한 표준을 준수하지 않는 통합을 사용하면 시스템 기능에 예기치 않은 장애가 발생할 수 있으며, 이는 비대면 카드 검증이 지원하거나 보증하지 않습니다.예: 웹뷰 내에서 Unico by iFrame을 구현하거나, HTML 태그를 통해 iFrame을 구현하는 경우 등.
### 일반 지침​

운영 성능을 최적화하고 전환율을 개선하며 더 부드러운 사용자 경험을 제공하려면, 애플리케이션에서 Unico SDK를 전체 화면 모드로 구현하는 것이 필수입니다.
### 시작하는 방법​

비대면 카드 검증 SDK를 통해 비대면 카드 검증을 사용하려면, 첫 번째 단계는 사용자 여정 경험을 표시할 호스트로 사용될 도메인을 등록하는 것입니다.
위험이 설정을 진행하려면 통합 프로젝트 담당자 또는 Unico 지원팀에 알리세요.
SDK 사용을 시작하려면, 먼저 Unico 웹 SDK 설치부터 진행해야 합니다:
```
npm install idpay-b2b-sdk
```

팁Unico SDK 패키지를 설치할 때, 사용 중인 버전을 명시하지 않고 배포하여 의존성 관리자가 항상 마이너 및 패치 버전을 최신으로 업데이트하도록 하세요.이전 버전을 확인하려면 [npmjs.com/package/idpay-b2b-sdk](https://www.npmjs.com/package/idpay-b2b-sdk?activeTab=versions)로 이동하세요.
### 사용 가능한 메서드​

#### `init(options)`​

이 메서드는 거래 ID와 관계없이 SDK를 초기화할 수 있게 하여 최종 사용자 경험을 더 부드럽게 만듭니다. 이는 거래 ID와 토큰이 사용 가능해질 때, 애플리케이션이 이 메서드를 통해 이미 사전 로드되어 있기 때문입니다. 애플리케이션에서 이 메서드를 직접 호출하지 않으면, SDK가 처음 열릴 때 최종 사용자는 긴 로딩 시간을 경험하게 됩니다.
매개변수:

`options` — 설정 속성을 담은 객체를 받습니다:

`type` — 초기화할 흐름의 유형입니다. 현재 저희는 `IFRAME` 유형을 제공합니다. 새로운 애플리케이션의 경우 `IFRAME` 유형을 사용하는 것을 권장합니다. 이는 체크아웃 화면을 벗어날 필요가 없고 경험을 사전 로드할 수 있어, 최종 사용자 경험을 훨씬 더 부드럽고 마찰 없이 만들어 줍니다.

```
import { IDPaySDK } from "idpay-b2b-sdk";IDPaySDK.init({  type: 'IFRAME',  env: 'uat' // Only needed for the test environment.});
```

#### `open({ transactionId, token, onFinish? })`​

이 메서드는 이전에 초기화 함수에서 선택한 흐름 유형에 따라 비대면 카드 검증 경험을 엽니다. REDIRECT 흐름의 경우, 이 함수는 비대면 카드 검증 캡처 흐름 라우트로 단순 리다이렉트를 수행합니다. IFRAME 흐름의 경우, 이 함수는 사전 로드된 iframe을 표시하고 고객 페이지와 비대면 카드 검증 경험 간의 메시징 흐름을 시작합니다.
매개변수:

`options` — 설정 속성을 담은 객체를 받습니다:

`transactionId` — 생성된 거래의 ID를 받습니다. 이 ID는 거래 세부 정보를 얻고 흐름을 올바르게 완료하는 데 중요합니다(API를 통한 거래 생성 시 얻을 수 있습니다).
`token` — 생성된 거래의 토큰을 받습니다. 이 토큰은 거래를 인증하고 승인된 도메인만 사용할 수 있도록 보장하는 데 중요합니다(API를 통한 거래 생성 시 얻을 수 있습니다).
`onFinish(transaction, type)`(선택 사항) — 비대면 카드 검증 캡처 흐름이 종료될 때 실행되는 콜백 함수를 받으며, 두 개의 인자를 전달합니다: 거래 객체(`{ captureConcluded, concluded, id }`)와 응답 유형 — 흐름이 성공적으로 완료된 경우 `FINISH`, 오류로 인해 흐름이 중단된 경우 `ERROR`입니다. 흐름에서 오류가 발생한 경우, 거래 상태는 변경되지 않으며, 설정된 경우에도 웹훅을 통한 콜백이 트리거되지 않습니다.

```
const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';const transaction = {  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',  concluded: true,  captureConcluded: true};const onFinish = (transaction, type) => {  console.log('response', transaction, type);}IDPaySDK.open({  transactionId,  token,  onFinish});// You can also close the SDK explicitly using the method belowIDPaySDK.close();
```

### 보안​

필요 사항과 과제를 신중히 분석한 후, 저희는 콘텐츠 보안 정책(Content Security Policy, CSP)을 구현하는 대신 인증 토큰을 사용하는 iFrame 기반 솔루션을 채택하기로 결정했습니다. 이 결정은 보안과 고객의 요구를 충족하는 데 필요한 유연성과 관련된 여러 고려 사항에 따른 것입니다.
#### CSP의 배경과 과제​

**콘텐츠 보안 정책(Content Security Policy, CSP)**은 **크로스 사이트 스크립팅(Cross-Site Scripting, XSS)**과 코드 삽입과 같은 다양한 유형의 공격으로부터 웹 애플리케이션을 보호하는 강력한 도구입니다. 하지만 CSP 정책을 설정할 때는 신뢰할 수 있는 도메인의 엄격한 목록을 정의해야 합니다. 이 접근 방식은 도메인이 고정되어 있고 예측 가능한 경우에는 잘 작동합니다. 하지만 동적이고 가변적인 도메인을 자주 사용하는 저희 고객들에게는 이러한 엄격한 설정이 상당한 어려움을 초래합니다.
#### 동적 도메인의 취약점​

동적 도메인은 CSP를 사용할 때 상당한 보안 위험을 초래합니다. 고객의 도메인이 자주 변경되거나 동적으로 생성되는 경우, 이러한 새 도메인을 포함하도록 CSP 정책을 지속적으로 업데이트해야 합니다. 이는 유지보수 부담을 늘릴 뿐만 아니라 CSP 정책이 적용되는 도메인을 노출시킵니다. CSP 정책에 추가된 각 도메인은 제대로 관리되지 않을 경우 잠재적인 취약점이 될 수 있습니다.
#### iFrame과 인증 토큰을 사용한 해결책​

이러한 위험을 완화하고 고객이 필요로 하는 유연성을 충족하기 위해, 저희는 인증 토큰과 결합된 iFrame을 사용하기로 결정했습니다. 이 솔루션은 추가적인 보안 계층을 제공하며, 광범위하고 동적인 도메인 목록을 노출하거나 관리할 필요를 없애줍니다.
#### 작동 방식​

**안전한 인증:** 각 iframe은 거래마다 고유한 인증 토큰과 함께 로드되어, 승인된 사용자만 콘텐츠에 접근할 수 있도록 보장합니다. 이 토큰은 실시간으로 검증되어 추가적인 보안 및 제어 계층을 제공합니다.
**콘텐츠 격리:** iFrame을 사용하면 콘텐츠를 별도의 컨텍스트에서 격리할 수 있어, 서로 다른 출처 간의 간섭 위험을 줄이고 잠재적인 공격을 완화합니다.
**동적 도메인에 대한 유연성:** 정적인 CSP 정책에 의존하지 않음으로써, 저희 솔루션은 보안 정책을 지속적으로 업데이트할 필요 없이 고객의 동적 도메인에 쉽게 적응합니다.
마지막 업데이트 2026년 10월 8일**에