웹 캡처

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

Markdown

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

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

token과 link는 생성 응답에서만 반환됩니다. 같은 요청에서 프론트엔드로 전달하거나 직접 저장하세요. 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로 제공해야 합니다. 카메라는 보안 컨텍스트에서만 작동합니다.
• 인앱 브라우징에는 Android 8(API 26) 또는 iOS 13 이상이 필요합니다.
• 소셜 네트워크 앱 내부의 브라우저는 지원되지 않습니다.

모델 선택

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

호스팅된 링크

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

{
  "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()으로 link를 열고, 탭이 callbackUri에 도달하는지 감시한 뒤 탭을 닫습니다.

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

Journeys SDK

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

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

1. 설치

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을 호출하세요. 캡처를 미리 로드합니다.

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

ByUnicoSDK.init({ token });

4. 캡처 열기

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

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는 사용자를 다음 화면으로 이동시키고, 사용자가 다시 시작할 때 곧바로 새 프로세스를 생성하지 않도록 하는 데에도 사용하세요.

문제 해결

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

테스트

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

지원되지 않는 구성

• 모바일 WebView 안의 SDK. 앱에서는 대신 link를 여세요. Android, iOS, Ionic, React Native, Flutter 가이드를 참고하세요.
• 캡처를 가리키는 직접 만든 <iframe>. iFrame을 관리하는 SDK를 사용하세요.