--- title: Webアプリ統合 description: クライアントサイドにおけるWeb & SDK契約の統合方法 — リダイレクトフローとiFrame SDKの設定。 canonical: https://developer.unico.io/ja/human-token/integrations/web/web-integration/ locale: ja generated_by: markdown-export --- このページでは、Unicoジャーニーの仕組みと、アプリケーションに組み込むために利用可能な統合モデルについて 説明します。 **ジャーニー**とは、ユーザーが本人確認を完了するために通過する一連のステップです。例えば、 書類の写真を撮影し、顔キャプチャ（ライブネス）を実行することです。 Unicoが体験全体を管理します。統合の手間は最小限です：ジャーニーは**CreateProcess**を通じて作成され、 ユーザーはそこに誘導され、最後に結果を受け取ります。その間のすべて — 画面、指示、 バリデーション — はすでにUnicoによって構築・保守されています。 ## 2つの統合モデル 各クライアントには異なるニーズがあります。Unicoはユーザーをジャーニーに誘導するための**2つのモデル**を提供しています。 | モデル | 最適な用途 | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **ダイレクトアクセス** | すでにWebViewを使用しているモバイルアプリケーション、またはメインページの外でジャーニーを実行できるWebフロー | | **Journeys SDK** | 統合されたシームレスな体験が必要で、ユーザーを同じ環境内に維持するWebアプリケーション | ### ダイレクトアクセス ユーザーは**Unicoがホストするリンクにリダイレクト**され、そこでジャーニーが行われます。完了すると、 プロセス作成時に定義されたURL（`callbackUri`パラメータ）に戻されます。 これは最も簡単な導入アプローチです：ライブラリのインストールが不要で、ジャーニーが アプリケーション自体のページ内で行われる必要がない場合にうまく機能します。一方で、ユーザーを クライアントの環境の外に連れ出すことは、より多くの摩擦を生み、結果としてより高い 離脱率につながる傾向があります。 プロセスを作成した後、APIレスポンスにはUnicoがホストするジャーニーのURLが含まれます。ユーザーを 誘導する一般的な方法が2つあります： - **標準リダイレクト。** ユーザーはジャーニーURLに直接リダイレクトされます。完了すると、 Unicoはプロセス作成時に定義された`callbackUri`にリダイレクトします。 - **`window.open()`による新しいタブ。** ジャーニーは新しいブラウザタブで開かれ、ユーザーは 別のコンテキストに保たれます。この場合、`callbackUri`へのURL変更を監視し、 プロセスが完了したらタブを閉じることが推奨されます。APIの詳細については [MDNドキュメント](https://developer.mozilla.org/en-US/docs/Web/API/Window/open)を参照してください。 ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` モバイルアプリケーションでは、追加のリダイレクトなしでジャーニーを直接開くために**WebView**を使用することが 一般的です。この場合、`callbackUri`は**ディープリンク**も受け付け、ジャーニーの完了により ネイティブアプリケーションの特定の画面を開くことができます。 ディープリンクを戻り先として設定するだけで、オペレーティングシステムがユーザーを 適切な場所にルーティングします。 ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### Journeys SDK ジャーニーはユーザーをコンテキストから外すことなく、**アプリケーション自体の内部で**行われます。 **Journeys SDK**がアプリケーションにインストールされ、必要に応じてジャーニーを開くために使用されます。 これは、より統合されたシームレスな体験のための推奨パスで、ユーザーを同じ環境に 維持し続けることで、フロー全体の摩擦と離脱を軽減する傾向があります。 Unicoは最新のブラウザと互換性のあるJavaScriptライブラリを提供しており、わずか数行のコードで 事実上あらゆるアプリケーションにジャーニーを統合できます。 #### 互換性 このライブラリは、使用中のスタックに関係なく、あらゆるプロジェクトに摩擦なく適合するよう設計されています： - **あらゆるWebアプリケーション。** UMD形式で配布され、最新のバンドラー（webpackやViteなど）を通じてインポートすると動作します。 あらゆるフレームワーク（React、Angular、Vue）またはプレーンJavaScriptと互換性があります。 - **最新のブラウザ。** ライブラリにはPromisesや`async/await`などの機能に必要な polyfillがすでに含まれており、古いブラウザバージョンとの互換性も拡張されています。 - **標準Web API。** ジャーニーはブラウザのネイティブ機能で動作し、プロジェクト内の プラグインや外部ライブラリへの依存はありません。 #### SDKの内部動作 ジャーニーが開かれると、SDKはページにiFrameを挿入し、その時点からビジュアル体験全体の 制御を引き受けます。各ステップの画面、スクリプト、アセットはこのiFrame内で実行され、 ユーザーが開始してからプロセスが完了するまで続きます。 このアーキテクチャ上の決定は意図的です：iFrameの分離により、Unicoジャーニーがアプリケーションの スタイルや動作に干渉しないことが保証されます。スクリプトが外部コンテキストに漏れることはなく、 CSSルールがアプリケーション独自のスタイルと衝突することもありません。結果として、エンドユーザーに 一貫した体験を提供し、クライアントの製品への影響を最小限に抑えます。 Unicoがiframeの作成と管理を担当しているため、ジャーニーの改善 — パフォーマンス、体験、 バリデーションのいずれであっても — すべてのユーザーに自動的に配信され、統合されたアプリケーションでの 変更は不要です。統合は常に利用可能な最適な最適化で実行され、プラットフォームの 各アップデートを追跡したり対応したりする必要はありません。 #### はじめに ****ステップ1** — インストール** `idpay-b2b-sdk`パッケージは、IDPay決済ジャーニーと本人確認ジャーニーの間で共有されています。 本人確認のユースケースでは、以下のステップに示すように`ByUnicoSDK`クラスをインポートしてください。 ```bash npm install idpay-b2b-sdk ``` Journeys SDKをインストールする推奨方法は、**npm registry**で利用可能なパッケージから、 **npm**や**yarn**などのパッケージマネージャーを使用することです。インストールと依存関係の管理を 簡素化するだけでなく、このアプローチは使用中のバージョンを明確に制御し、 新しいバージョンが公開された際の更新を簡単にします。 SDKは**セマンティックバージョニング（SemVer）**に従っており、パッチおよびマイナーアップデートは 破壊的変更を導入しません。これらのアップデートを自動的に受信するようにプロジェクトを設定することは 安全です。統合の更新が必要になる可能性のある変更はメジャーバージョンに予約されており、常に 移行ガイドが付属します。 :::tip[SDKを最新に保つ] 最新バージョンを維持することは、2つの理由で特に重要です。1つ目は**セキュリティ**です： 脆弱性が特定されたり、通信プロトコルを強化する機会が生じたりするたびに、 セキュリティパッチが公開されます。古いバージョンを実行することは、これらの修正を逃し、 フローを不必要なリスクにさらすことを意味します。2つ目は**安定性**です：バグ修正は 同様に配布され、古いバージョンではより新しいリリースですでに解決された動作が 発生する可能性があります。 ::: 開始する前に、Unicoサポートチームにドメインを登録してください。すべてのドメインは HTTPSを使用する必要があります。 ****ステップ2** — CSP と Permissions-Policy を設定** ページがすでに`Content-Security-Policy`または`Permissions-Policy`ヘッダーを送信している場合、SDKのiFrame、スクリプト、カメラアクセスが正しく機能するように、以下のディレクティブを追加してください。 **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"); ``` :::info ページがCSPまたはPermissions-Policyヘッダーを送信していない場合、このステップをスキップできます — ブラウザはデフォルトで制限を適用しません。 ::: ****ステップ3** — `init(options)`を呼び出す** SDKを初期化し、ジャーニーが正しく機能するために必要なスクリプトをプリロードし、 エンドユーザーにとってよりスムーズな体験を作り出します。フローのできるだけ早い段階で呼び出してください。 | パラメータ | 必須 | 説明 | | --------- | -------- | ------------------------------------------------ | | `token` | はい | Create Process APIが返すプロセストークン | | `env` | いいえ | テスト環境専用で`'uat'`に設定 | ```javascript import { ByUnicoSDK } from 'idpay-b2b-sdk'; ByUnicoSDK.init({ token, // env: 'uat' // only for test environments }); ``` ****ステップ4** — `open(options)`を呼び出す** iFrameを表示し、ユーザーのジャーニーを開始します。この時点以降、すべてがiFrame内で 自動的に行われ、中間ステップを管理する必要はありません。 | パラメータ | 必須 | 説明 | | -------------------------- | -------- | ---------------------------------------------------------- | | `transactionId` | はい | Create Process APIが返すプロセスID | | `token` | はい | Create Process APIが返すプロセストークン | | `onFinish` | はい | ジャーニーが終了または閉じられたときに実行されるコールバック | | `onWidgetVisibilityChange` | いいえ | ウィジェットの表示状態が変更されたときに実行されるコールバック | アプリケーションとの次のインタラクションは、ユーザーがジャーニーを完了したか閉じたかに関わらず、 ジャーニーが終了したときに発生します。その時点で、SDKは`open`にパラメータとして渡された **`onFinish`**コールバックを呼び出します。そこから、アプリケーションは**`getProcess`** APIを呼び出して 結果を確認するか、非同期アプローチが好ましい場合は**Webhook**通知を待つことができます。 結果のクエリに加えて、アプリケーションのフロントエンド状態を処理するために`onFinish`を使用する ことが推奨されます： - **ループを避ける。** ジャーニー終了直後にユーザーがフローを再度トリガーした場合の、 プロセスの即時かつ不要な再作成を防止します。 - **フロー管理。** ユーザーがアプリケーションの次のステップに誘導されるようにし、 ジャーニーの終了後にデッドエンド画面を回避します。 :::warning `onFinish`コールバックはユーザーがジャーニーを完了したことを示しますが、承認を保証するものではありません。 プロセスはUnicoのバリデーションルールのいずれかで失敗して終了した可能性があります。 `getProcess`によるクエリまたはWebhook通知の受信は任意ではありません：これらが実際の結果の 唯一のソースであり、アプリケーションの動作はこれらに基づく必要があります。`onFinish`を 単独でユーザーが承認されたかどうかを判断するために使用してはなりません。 ::: `onFinish`コールバックは、ジャーニーがどのように終了したかを記述するオブジェクトを受け取ります： | フィールド | 型 | 説明 | | ------------------------- | ------------------- | ----------------------------------------------------------------------------------------- | | `type` | string | ジャーニーの終了方法：`'FINISH'`（完了）または`'CLOSE'`（ユーザーが完了前に閉じた） | | `transaction` | object \| undefined | `type`が`'FINISH'`の場合に存在；`type`が`'CLOSE'`の場合は`undefined` | | `transaction.id` | string | プロセス識別子（渡された`transactionId`と同じ） | | `transaction.redirectUrl` | string | ジャーニー後にユーザーをリダイレクトするURL | **`onWidgetVisibilityChange`**コールバックの処理は任意で、ユースケースに関連しない場合があります。 ウィジェットの表示状態が変更されるたびに呼び出され、特定のシナリオでのみ有用です： 一部のジャーニーは透明な背景を表示し、体験の背後にアプリケーションページを表示したままにします。 検証フロー中にカスタムモーダルを表示するアプリケーション（例えば、複数のKYCプロバイダー間の オーケストレーションの一部として）は、そのモーダルをUnicoウィジェットの背後に表示してしまい、 ビジュアル体験を損なう可能性があります。その場合、コールバックによりアプリケーションは Unicoジャーニーがアクティブな間、追加のビジュアル要素を抑制し、終了後に復元できます。 アプリケーションにウィジェットと重なる可能性のあるUIがない場合は、安全に省略できます。 ```javascript ByUnicoSDK.open({ transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf', token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', onFinish: ({ transaction, type }) => { if (type === 'FINISH') { // Journey completed (transaction = { id, redirectUrl }) — continue your flow here. } // type === 'CLOSE' → user closed before finishing; }, // Optional: only needed if your app shows UI that could overlap the widget. onWidgetVisibilityChange: (visible) => { // suppress or restore your modal based on widget visibility }, }); // To close the SDK explicitly at any point: ByUnicoSDK.close(); ``` 以下のシーケンス図は、SDKとAPIの結果を使用してiFrameを構成する方法を示しています： ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### サンプルアプリ | 言語 / フレームワーク | 説明 | リポジトリ | | --------------------- | ------------ | ---------- | | Angular | Journeys SDKを実装したAngularのPoC | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | Journeys SDKを実装したJS VanillaのPoC | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | Journeys SDKを実装したReactのPoC | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | Journeys SDKを実装したVue JSのPoC | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### セキュリティ このモデルのセキュリティは、SDKとiFrame内で実行されるアプリケーション間の通信プロトコルから 始まるレイヤーで構築されています。 ジャーニーが読み込まれると、両者は通信を確立するために**ハンドシェイク**を実行します。この プロセスで、Unicoアプリケーションは`postMessage`を介して受信したデータインジェクションメッセージの オリジンを、環境（UATおよびPROD）ごとに分割された承認済みドメインのクローズドリストに対して 検証します。承認されていないオリジンからのメッセージは即座に破棄され、ジャーニーが 未承認のページに埋め込まれることを防ぎ、**クリックジャッキング**などの脆弱性の攻撃面を 排除します。 オリジンの検証に加えて、フローは有効なトランザクショントークンでのみ進行します： Unicoバックエンドが発行・署名したワンタイムJWTです。これにより、承認されたオリジンであっても、 期限切れ、再利用、または偽造されたトークンでは操作できないことが保証されます。 ハンドシェイク後、トークンはiFrameに注入され、両者間で機密情報は流れません。残りの すべての通信は、インターフェース制御のためにのみ機能します — 開く、閉じる、画面遷移 — ジャーニー中のプロセスデータの傍受や漏洩を防ぎます。 iFrameの分離は、ランタイム時のUnicoスクリプトの整合性も保護します。コードは ページとは別のコンテキストで実行されるため、外部スクリプトからアクセスまたは変更できず、 ジャーニーが構築された通りに正確に実行されることが保証され、干渉を受けません。 ##### CSP と Permissions-Policy ページが`Content-Security-Policy`または`Permissions-Policy`ヘッダーを送信している場合、SDKのiFrame、スクリプト、カメラアクセスが正しく機能するように、以下のディレクティブが存在することを確認してください。 **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"); ``` ページがこれらのヘッダーを送信していない場合、ブラウザはデフォルトで制限を適用せず、設定は不要です。 #### SDK固有のトラブルシューティング このセクションでは、統合中に発生する最も一般的な問題と、それらを調査するための推奨方法について 説明します。 ##### 予期しない動作やフローの中断 アプリケーションスクリプトがDOM内のiFrameを直接操作していないか確認してください。SDKは ページの`body`にiFrameを作成・管理しており、スコープ、ポジショニング、属性への外部の 変更はジャーニーのライフサイクルに干渉し、予測できない動作を引き起こす可能性があります。 ##### 期待と異なるビジュアル体験 アプリケーションのグローバルスタイルシートがiFrame内のプロパティをオーバーライドしていないか 確認してください。SDKはiFrameとそのすべての内部要素を動的なIDと`unico`プレフィックスの クラスで作成し、IDやクラスセレクターによる競合のリスクを大幅に削減します。それでも、 タグセレクターなどの広範なCSSルールはiFrame内の要素に到達し、ユーザーに提供される ビジュアル体験を変更する可能性があります。 ##### SDKライブラリファイルの直接変更 パッケージマネージャーの外でライブラリファイルが変更されていないか確認してください。ライブラリは **npm**または**yarn**を通じて排他的に管理する必要があり、インストール済みファイルの直接編集は 行わないでください。手動の変更は再現困難な異常な動作を生じさせ、Unicoサポートが 支援できなくなる可能性があります。 #### キャプチャテスト中にDevToolsを開いたままにしないでください UnicoアプリケーションはCapture SDK（unico-webframe）を使用して顔キャプチャを行いますが、開いているDevToolsを潜在的な不正信号として検出し、送信をブロックします。エンドツーエンドのキャプチャテストを実行する前にDevToolsを閉じてください。 :::warning[サポートされていない統合] このドキュメントで説明されているモデル — ダイレクトアクセスとJourneys SDK — は、Unicoが公式に サポートする唯一の統合アプローチです。これらの基準から逸脱する統合は、予期しない動作、 セキュリティフローの失敗、ジャーニーの中断を引き起こす可能性があり、Unicoサポートの 対象外となります。 サポートされていないアプローチの例： - モバイルアプリケーションで**SDKをWebView内に埋め込む**。これらの場合、正しいアプローチは Journeys SDKを使用せずに、WebViewでジャーニーリンクを直接開く**ダイレクトアクセス**モデルを 使用することです。 - **Journeys SDKを経由せずに`