---
title: Webキャプチャ
description: Human Plugin の作成リクエストが返す値を使い、ホスト型リンクまたは Journeys SDK で、Webアプリケーション上の Journey フローのキャプチャを実行します。
canonical: https://developer.unico.io/ja/human-plugin/integrations/web
locale: ja
generated_by: markdown-export
---

# Webキャプチャ

Human Plugin が返すトークンとリンクを使って、ブラウザ上でユーザーにキャプチャを行ってもらいます。

バックエンドは、Journey フローを指定して Human Plugin にプロセスを作成します。`201` レスポンスには、フロントエンドに必要な3つの値が含まれます。

| フィールド | 用途 |
|---|---|
| `id` | Human Plugin のプロセス ID。SDK では `transactionId` として渡し、バックエンドはこの ID で結果を読み取ります |
| `token` | Journeys SDK でキャプチャを開始します |
| `link` | ホスト型のキャプチャページ |

`token` と `link` が返されるのは作成時の**1回のみ**です。同じリクエスト内でフロントエンドに渡すか、自身で保存してください。[Human Token Journey](/ja/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"
}
```

次に、2つの方法のいずれかでユーザーを `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 はセマンティックバージョニングに従うため、マイナーおよびパッチの更新は安全に取り込めます。常に最新の状態を保ってください。セキュリティ修正やバグ修正は新しいバージョンで提供されます。

#### 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, // Human Plugin の id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // キャプチャが終了しました。バックエンドに結果の読み取りを依頼します。
    }
    // type === 'CLOSE': ユーザーが終了前に閉じました。
  },
  // 任意: キャプチャの表示中は、独自のオーバーレイを非表示にします。
  onWidgetVisibilityChange: (visible) => {},
});

// 自分で閉じる場合:
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 経由でのみインストールし、ファイルを編集しないでください。

> **情報: テスト**
>
> キャプチャをエンドツーエンドでテストする前に、ブラウザの DevTools を閉じてください。DevTools が開いていると、送信がブロックされます。

> **警告: サポートされない構成**
>
> - **モバイルの WebView 内での SDK。** アプリでは、代わりに `link` を開いてください。[Android](/ja/human-plugin/integrations/android)、[iOS](/ja/human-plugin/integrations/ios)、[Ionic](/ja/human-plugin/integrations/ionic)、[React Native](/ja/human-plugin/integrations/react-native)、[Flutter](/ja/human-plugin/integrations/flutter) の各ガイドを参照してください。
> - **キャプチャを指す独自の `<iframe>`。** iFrame を管理する SDK を使用してください。