Webキャプチャ

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

Markdown

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

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

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

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

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, // 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 は、ユーザーを次の画面に移動させる場合や、ユーザーがやり直したときにすぐ新しいプロセスを作成しないようにする場合にも使用してください。

トラブルシューティング

• フローが中断する、または挙動がおかしい。 自身のスクリプトが DOM 内の SDK の iFrame を変更していないことを確認してください。
• キャプチャの見た目が異なる。 タグセレクターのような広範な CSS ルールが iFrame に影響することがあります。SDK 独自の ID とクラスは unico で始まります。
• 更新後に予期しないエラーが発生する。 SDK は npm または yarn 経由でのみインストールし、ファイルを編集しないでください。

テスト

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

サポートされない構成

• モバイルの WebView 内での SDK。 アプリでは、代わりに link を開いてください。Android、iOS、Ionic、React Native、Flutter の各ガイドを参照してください。
• キャプチャを指す独自の <iframe>。 iFrame を管理する SDK を使用してください。