Webアプリ統合
このページでは、Unicoジャーニーの仕組みと、アプリケーションに組み込むために利用可能な統合モデルについて 説明します。
ジャーニーとは、ユーザーが本人確認を完了するために通過する一連のステップです。例えば、 書類の写真を撮影し、顔キャプチャ（ライブネス）を実行することです。
Unicoが体験全体を管理します。統合の手間は最小限です：ジャーニーはCreateProcessを通じて作成され、 ユーザーはそこに 誘導され、最後に結果を受け取ります。その間のすべて — 画面、指示、 バリデーション — はすでにUnicoによって構築・保守されています。
2つの統合モデル
各クライアントには異なるニーズがあります。Unicoはユーザーをジャーニーに誘導するための2つのモデルを提供しています。
| モデル | 最適な用途 |
|---|---|
| ダイレクトアクセス | すでにWebViewを使用しているモバイルアプリケーション、またはメインページの外でジャーニーを実行できるWebフロー |
| Journeys SDK | 統合されたシームレスな体験が必要で、ユーザーを同じ環境内に維持するWebアプリケーション |
- ダイレクトアクセス
- Journeys SDK
ユーザーはUnicoがホストするリンクにリダイレクトされ、そこでジャーニーが行われます。完了すると、
プロセス作成時に定義されたURL（callbackUriパラメータ）に戻されます。
これは最も簡単な導入アプローチです：ライブラリのインストールが不要で、ジャーニーが アプリケーション自体の ページ内で行われる必要がない場合にうまく機能します。一方で、ユーザーを クライアントの環境の外に連れ出すことは、より多くの摩擦を生み、結果としてより高い 離脱率につながる傾向があります。
プロセスを作成した後、APIレスポンスにはUnicoがホストするジャーニーのURLが含まれます。ユーザーを 誘導する一般的な方法が2つあります：
- 標準リダイレクト。 ユーザーはジャーニーURLに直接リダイレクトされます。完了すると、
Unicoはプロセス作成時に定義された
callbackUriにリダイレクトします。 window.open()による新しいタブ。 ジャーニーは新しいブラウザタブで開かれ、ユーザーは 別のコンテキストに保たれます。この場合、callbackUriへのURL変更を監視し、 プロセスが完了したらタブを閉じることが推奨されます。APIの詳細については MDNドキュメントを参照してください。
モバイルアプリケーションでは、追加のリダイレクトなしでジャーニーを直接開くためにWebViewを使用することが
一般的です。この場合、callbackUriはディープリンクも受け付け、ジャーニーの完了により
ネイティブアプリケーションの特定の画面を開くことができます。
ディープリンクを戻り先として設定するだけで、オペレーティングシステムがユーザーを
適切な場所にルーティングします。
ジャーニーはユーザーをコンテキストから外すことなく、アプリケーション自体の内部で行われます。 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クラスをインポートしてください。
npm install idpay-b2b-sdk
Journeys SDKをインストールする推奨方法は、npm registryで利用可能なパッケージから、 npmやyarnなどのパッケージマネージャーを使用することです。インストールと依存関係の管理を 簡素化するだけでなく、このアプローチは使用中のバージョンを明確に制御し、 新しいバージョンが公開された際の更新を簡単にします。
SDKは**セマンティックバージョニング（SemVer）**に従っており、パッチおよびマイナーアップデートは 破壊的変更を導入しません。これらのアップデートを自動的に受信するようにプロジェクトを設定することは 安全です。統合の更新が必要になる可能性のある変更はメジャーバージョンに予約されており、常に 移行ガイドが付属します。
最新バージョンを維持することは、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");
ページがCSPまたはPermissions-Policyヘッダーを送信していない場合、このステップをスキップできます — ブラウザはデフォルトで制限を適用しません。
ステップ3 — init(options)を呼び出す
SDKを初期化し、ジャーニーが正しく機能するために必要なスクリプトをプリロードし、 エンドユーザーにとってよりスムーズな体験を作り出します。フローのできるだけ早い段階で呼び出してください。
| パラメータ | 必須 | 説明 |
|---|---|---|
token | はい | Create Process APIが返すプロセストークン |
env | いいえ | テスト環境専用で'uat'に設定 |
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を使用する
ことが推奨されます：
- ループを避ける。 ジャーニー終了直後にユーザーがフローを再度トリガーした場合の、 プロセスの即時かつ不要な再作成を防止します。
- フロー管理。 ユーザーがアプリケーションの次のステップに誘導されるようにし、 ジャーニーの終了後にデッドエンド画面を回避します。
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がない場合は、安全に省略できます。
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を構成する方法を示しています：
サンプルアプリ
| 言語 / フレームワーク | 説明 | リポジトリ |
|---|---|---|
| Angular | Journeys SDKを実装したAngularのPoC | GitHub — unico-cbu-poc-angular |
| JS Vanilla | Journeys SDKを実装したJS VanillaのPoC | GitHub — unico-cbu-poc-js |
| React | Journeys SDKを実装したReactのPoC | GitHub — unico-cbu-poc-react |
| Vue JS | Journeys SDKを実装したVue JSのPoC | GitHub — 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を閉じてください。
このドキュメントで説明されているモデル — ダイレクトアクセスとJourneys SDK — は、Unicoが公式に サポートする唯一の統合アプローチです。これらの基準から逸脱する統合は、予期しない動作、 セキュリティフローの失敗、ジャーニーの中断を引き起こす可能性があり、Unicoサポートの 対象外となります。
サポートされていないアプローチの例：
- モバイルアプリケーションでSDKをWebView内に埋め込む。これらの場合、正しいアプローチは Journeys SDKを使用せずに、WebViewでジャーニーリンクを直接開くダイレクトアクセスモデルを 使用することです。
- Journeys SDKを経由せずに
<iframe>HTMLタグでiFrameを直接読み込む。iFrameは SDKの内部実装の詳細であり、手動でインスタンス化してはなりません。正しいアプローチは Journeys SDKを使用することで、これはiFrameのライフサイクルを安全に、期待される基準内で 管理します。
アプローチがサポートされている基準内かどうかに疑問がある場合は、実装を進める前に ドキュメントを参照するかサポートに連絡してください。