--- title: Webアプリ統合 description: クライアントサイドにおけるWeb & SDK契約の統合方法 — リダイレクトフローとiFrame SDKの設定。 canonical: https://developer.unico.io/ja/dual-api/developers/sdks-and-tools/web/web-integration/ locale: ja generated_by: markdown-export --- このページでは、Unicoのジャーニーがどのように機能するか、そしてそれをアプリケーションに組み込むために利用できる統合モデルについて説明します。 **ジャーニー**とは、本人確認を完了するためにユーザーが通過する一連のステップです。たとえば、書類の写真を撮影する、顔のキャプチャ（ライブネス）を行う、といったものです。 Unicoが体験全体を管理します。統合の手間は最小限です。ジャーニーは**CreateProcess**を介して作成され、ユーザーはそこへ誘導され、最後に結果を受け取ります。その間に起こること（画面、指示、検証）はすでに構築されており、Unicoが保守しています。 :::tip[統合アプローチの選択] - **Web SDK**（`unico-webframe`パッケージ）: バックエンドがすでに本人確認フローを制御しており、クライアントサイドのキャプチャコンポーネントのみが必要な場合に使用します。`base64` + 暗号化されたJWTをコールバックに直接返します。API呼び出しはご自身で管理します。 - **Web App Integration**（`idpay-b2b-sdk`パッケージ）: Unicoにジャーニー全体（マルチステップフロー、書類キャプチャ + ライブネス）をオーケストレーションしてほしい場合に使用します。`idpay-b2b-sdk`パッケージは埋め込み型の**Journeys SDK**（iFrame）モデルを実現します。**直接アクセス**（リダイレクト）モデルにライブラリは不要です。 ::: ## 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`などの機能に必要なポリフィルがすでに含まれており、古いバージョンのブラウザへの互換性も拡張します。 - **標準的な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**や**yarn**などのパッケージマネージャーを使い、**npm registry**で公開されているパッケージからインストールすることです。インストールと依存関係の管理が簡素化されるだけでなく、この方法では使用しているバージョンを明確に制御でき、新しいバージョンが公開されるたびに簡単に更新できます。 SDKは**セマンティックバージョニング（SemVer）**に従っており、patchおよびminorの更新では互換性を破壊する変更は導入されません。これらの更新を自動的に受け取るようにプロジェクトを構成しても安全です。統合の調整が必要になる可能性のある変更はmajorバージョンに限定され、常に移行ガイドが付属します。 :::tip[SDKを最新の状態に保つ] 最新バージョンを維持することは、2つの理由から特に重要です。1つ目は**セキュリティ**です。脆弱性が特定されたとき、または通信プロトコルを強化する機会が生じたときには、必ずセキュリティパッチが公開されます。古いバージョンを使用することは、これらの修正を見送り、フローを不要なリスクにさらすことを意味します。2つ目は**安定性**です。バグ修正も同じ方法で配布され、古いバージョンには、より新しいリリースですでに解決済みの挙動が残っている可能性があります。 ::: 始める前に、Unicoのサポートチームにドメインを登録してください。すべてのドメインはHTTPSを使用する必要があります。 ****ステップ2**: `init(options)`を呼び出す** SDKを初期化し、ジャーニーが正しく機能するために必要なスクリプトを事前に読み込み、エンドユーザーにより滑らかな体験を提供します。フローのできるだけ早い段階で呼び出してください。 | パラメータ | 必須 | 説明 | | ---------- | ------ | ----------------------------------------------- | | `token` | はい | Create Process APIから返されるプロセストークン | | `env` | いいえ | テスト環境の場合のみ`'uat'`を設定 | ```javascript import { ByUnicoSDK } from 'idpay-b2b-sdk'; ByUnicoSDK.init({ token, // env: 'uat' // テスト環境の場合のみ }); ``` ****ステップ3**: `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') { // ジャーニー完了（transaction = { id, redirectUrl }）: ここで自身のフローを続行します。 } // type === 'CLOSE' → ユーザーが完了前に閉じた; }, // 任意: ウィジェットと重なる可能性のあるUIをアプリが表示する場合にのみ必要。 onWidgetVisibilityChange: (visible) => { // ウィジェットの表示状態に応じてモーダルを非表示または復元する }, }); // SDKをいつでも明示的に閉じるには: 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) | #### セキュリティ :::note[このセクションの範囲] このセキュリティに関する論拠は、特に**Web App Integration**（`idpay-b2b-sdk`）に適用されます。**Web SDK**（`unico-webframe`）は異なるモデルを使用しており、完全にページのコンテキスト内で動作し、[CSPを必要とします](/dual-api/developers/sdks-and-tools/web/web-sdk/installation)。これらは、異なるセキュリティアーキテクチャを持つ2つの異なる製品です。 ::: このモデルのセキュリティは、SDKとiFrame内で動作するアプリケーションの間の通信プロトコルを起点として、層状に構築されています。 ジャーニーが読み込まれると、両者は通信を確立するために**ハンドシェイク**を実行します。この過程で、Unicoのアプリケーションは`postMessage`経由で受信したデータ注入メッセージのオリジンを、環境（UATおよびPROD）ごとに区分された認可済みドメインのクローズドリストと照合して検証します。認可されていないオリジンからのメッセージは直ちに破棄され、これによりジャーニーが認可されていないページに埋め込まれるのを防ぎ、**クリックジャッキング**などの脆弱性に対する攻撃対象領域を排除します。 オリジンの検証に加えて、フローは有効なトランザクショントークン（Unicoのバックエンドが発行し署名した使い捨てのJWT）がある場合にのみ進行します。これにより、認可済みのオリジンであっても、期限切れ・再利用・偽造されたトークンでは動作できないことが保証されます。 ハンドシェイクの後、トークンはiFrameに注入され、両者の間で機密情報がやり取りされることはなくなります。残りのすべての通信はインターフェース制御（開く、閉じる、画面遷移）のためだけに使われ、ジャーニー中にプロセスのデータが傍受または漏洩するのを防ぎます。 iFrameの分離は、実行時におけるUnicoスクリプトの整合性も保護します。コードはページから分離されたコンテキストで実行されるため、外部のスクリプトからアクセスされたり変更されたりすることはなく、ジャーニーが構築されたとおりに、干渉を受けずに実行されることが保証されます。 設計上、この統合モデルではCSPを採用していません。認可済みドメインは各クライアントのセキュリティ構成の一部であり、それをヘッダーで公開すると、悪意のある攻撃者によるインフラのマッピングを容易にしてしまう恐れがあります。クライアントの識別は`init`の時点でのみ行われるため、その前にこれらのドメインをヘッダーに動的に挿入することはできず、この機密性を犠牲にせずにCSPを実現することは不可能です。すべてのセキュリティ保証は、上記のハンドシェイクプロトコルによって提供されます。 #### 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を介さずに、HTMLの`