---
title: 웹 캡처
description: Human Plugin 생성 응답이 반환하는 값을 사용해, 호스팅된 링크 또는 Journeys SDK로 웹 애플리케이션에서 Journey 플로우의 캡처를 실행합니다.
canonical: https://developer.unico.io/ko/human-plugin/integrations/web
locale: ko
generated_by: markdown-export
---

# 웹 캡처

Human Plugin이 반환한 토큰과 링크를 사용해 브라우저에서 캡처를 진행합니다.

백엔드가 Journey 플로우로 Human Plugin에 프로세스를 생성합니다. `201` 응답에는 프론트엔드에 필요한 세 가지 값이 있습니다.

| 필드 | 용도 |
|---|---|
| `id` | Human Plugin 프로세스 id입니다. SDK는 이를 `transactionId`로 받고, 백엔드는 이 값으로 결과를 조회합니다 |
| `token` | Journeys SDK에서 캡처를 시작합니다 |
| `link` | 호스팅된 캡처 페이지입니다 |

`token`과 `link`는 생성 응답에서**만** 반환됩니다. 같은 요청에서 프론트엔드로 전달하거나 직접 저장하세요. [Human Token Journey](/ko/human-plugin/integrations/human-token-journey)를 참고하세요.

## 요구 사항

캡처는 브라우저에서 실행되며 카메라 접근이 필요합니다.

| OS | Chrome | Firefox | Safari | Samsung Internet | Opera | Edge |
|---|---|---|---|---|---|---|
| Windows | ✅ | ✅ | N/A | N/A | ❌ | ❌ |
| macOS | ✅ | ✅ | ✅ | N/A | ❌ | ❌ |
| Android | ✅ | ❌ | N/A | ✅ | ❌ | ❌ |
| iOS | ✅ | ✅ | ✅ | N/A | ❌ | ❌ |

- 페이지는 **HTTPS**로 제공해야 합니다. 카메라는 [보안 컨텍스트](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)에서만 작동합니다.
- 인앱 브라우징에는 Android 8(API 26) 또는 iOS 13 이상이 필요합니다.
- 소셜 네트워크 앱 내부의 브라우저는 지원되지 않습니다.

## 모델 선택

| 모델 | 적합한 경우 |
|---|---|
| **호스팅된 링크** | 가장 간단한 설정입니다. 라이브러리가 필요 없습니다. 사용자는 `link`로 이동했다가 `callbackUri`로 돌아옵니다 |
| **Journeys SDK** | 캡처가 고객의 페이지 안에서 열리므로 사용자가 페이지를 떠나지 않습니다 |

### 호스팅된 링크

생성 요청에 `callbackUri`를 보내세요. 캡처가 끝나면 사용자가 돌아오는 페이지입니다.

```json
{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}
```

그런 다음 두 가지 방법 중 하나로 사용자를 `link`로 보내세요.

- **리디렉션.** `link`로 이동합니다. 끝나면 사용자가 `callbackUri`로 돌아옵니다.
- **새 탭.** [`window.open()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open)으로 `link`를 열고, 탭이 `callbackUri`에 도달하는지 감시한 뒤 탭을 닫습니다.

사용자가 돌아오면 백엔드에 알리세요. 백엔드가 `GET /v1/processes/{id}`를 호출합니다.

```mermaid
sequenceDiagram
  participant F as Your front-end
  participant B as Your back-end
  participant H as Human Plugin
  participant P as Hosted page
  F->>B: start the capture
  B->>H: POST /v1/processes (Journey flow, callbackUri)
  H-->>B: 201, id + token + link
  B-->>F: id + link
  F->>P: open link
  Note over P: capture
  P-->>F: back to callbackUri
  F->>B: capture ended
  B->>H: GET /v1/processes/{id}
  H-->>B: 200, final state
```

### Journeys SDK

SDK는 고객의 페이지에 iFrame으로 캡처를 엽니다. 모든 프레임워크(React, Angular, Vue) 또는 순수 JavaScript에서 작동합니다.

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

#### 1. 설치

```bash
npm install unico-journey-sdk
```

SDK는 유의적 버전(semantic versioning)을 따르므로 마이너 및 패치 업데이트는 안전하게 적용할 수 있습니다. 보안 및 버그 수정은 새 버전으로 배포되므로 최신 상태를 유지하세요.

#### 2. 헤더에서 SDK 허용

페이지가 `Content-Security-Policy` 또는 `Permissions-Policy` 헤더를 보내지 않는다면 이 단계를 건너뛰세요. 그렇지 않다면 다음을 추가하세요.

**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")
```

#### 3. 초기화

캡처가 필요하다는 것을 알게 되는 즉시 `init`을 호출하세요. 캡처를 미리 로드합니다.

```javascript
import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });
```

#### 4. 캡처 열기

| 매개변수 | 필수 | 값 |
|---|---|---|
| `transactionId` | 예 | Human Plugin의 `id` |
| `token` | 예 | 생성 응답의 `token` |
| `onFinish` | 예 | 캡처가 끝나거나 사용자가 닫을 때 호출됩니다 |
| `onWidgetVisibilityChange` | 아니요 | 캡처가 표시되거나 숨겨질 때 호출됩니다 |

```javascript
ByUnicoSDK.open({
  transactionId: id, // the Human Plugin id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // The capture ended. Ask your back-end to read the outcome.
    }
    // type === 'CLOSE': the person closed it before the end.
  },
  // Optional: hide your own overlays while the capture is visible.
  onWidgetVisibilityChange: (visible) => {},
});

// To close it yourself:
ByUnicoSDK.close();
```

`onFinish`는 다음을 받습니다.

| 필드 | 설명 |
|---|---|
| `type` | 캡처가 끝났으면 `'FINISH'`, 사용자가 먼저 닫았으면 `'CLOSE'` |
| `transaction.redirectUrl` | 사용자를 다음에 보낼 위치입니다. `'FINISH'`일 때만 존재합니다 |

> **경고:** `onFinish`는 캡처가 끝났다는 것만 알려주고, 어떻게 끝났는지는 알려주지 않습니다. 결과는 백엔드의 `GET /v1/processes/{id}`에서만 얻을 수 있습니다.

`onFinish`는 사용자를 다음 화면으로 이동시키고, 사용자가 다시 시작할 때 곧바로 새 프로세스를 생성하지 않도록 하는 데에도 사용하세요.

```mermaid
sequenceDiagram
  participant F as Your front-end
  participant S as Journeys SDK
  participant B as Your back-end
  participant H as Human Plugin
  F->>B: start the capture
  B->>H: POST /v1/processes (Journey flow)
  H-->>B: 201, id + token + link
  B-->>F: id + token
  F->>S: init({ token })
  F->>S: open({ transactionId: id, token, onFinish })
  Note over S: capture
  S-->>F: onFinish
  F->>B: capture ended
  B->>H: GET /v1/processes/{id}
  H-->>B: 200, final state
```

#### 문제 해결

- **플로우가 중단되거나 이상하게 동작합니다.** 고객의 스크립트가 DOM에서 SDK의 iFrame을 변경하지 않는지 확인하세요.
- **캡처 화면이 다르게 보입니다.** 태그 선택자 같은 광범위한 CSS 규칙이 iFrame에 영향을 줄 수 있습니다. SDK 자체의 id와 클래스는 `unico`로 시작합니다.
- **업데이트 후 예기치 않은 오류가 발생합니다.** SDK는 npm 또는 yarn으로만 설치하고, SDK 파일은 절대 수정하지 마세요.

> **정보: 테스트**
>
> 캡처를 처음부터 끝까지 테스트하기 전에 브라우저 DevTools를 닫으세요. DevTools가 열려 있으면 제출이 차단됩니다.

> **경고: 지원되지 않는 구성**
>
> - **모바일 WebView 안의 SDK.** 앱에서는 대신 `link`를 여세요. [Android](/ko/human-plugin/integrations/android), [iOS](/ko/human-plugin/integrations/ios), [Ionic](/ko/human-plugin/integrations/ionic), [React Native](/ko/human-plugin/integrations/react-native), [Flutter](/ko/human-plugin/integrations/flutter) 가이드를 참고하세요.
> - **캡처를 가리키는 직접 만든 `<iframe>`.** iFrame을 관리하는 SDK를 사용하세요.