Webアプリ統合

このページでは、Unicoのジャーニーがどのように機能するか、そしてそれをアプリケーションに組み込むために利用できる統合モデルについて説明します。

ジャーニーとは、本人確認を完了するためにユーザーが通過する一連のステップです。たとえば、書類の写真を撮影する、顔のキャプチャ（ライブネス）を行う、といったものです。

Unicoが体験全体を管理します。統合の手間は最小限です。ジャーニーはCreateProcessを介して作成され、ユーザーはそこへ誘導され、最後に結果を受け取ります。その間に起こること（画面、指示、検証）はすでに構築されており、Unicoが保守しています。

統合アプローチの選択

• 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のドキュメントを参照してください。

モバイルアプリでは、追加のリダイレクトなしにジャーニーを直接開くためにWebViewを使用するのが一般的です。この場合、callbackUriはディープリンクも受け付けます。これにより、ジャーニーの完了をきっかけにネイティブアプリ内の特定の画面を開くことができます。ディープリンクを戻り先として設定するだけで、オペレーティングシステムがユーザーを適切な場所へルーティングします。

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クラスをインポートします。

  npm install idpay-b2b-sdk

Journeys SDKをインストールする推奨方法は、npmやyarnなどのパッケージマネージャーを使い、npm registryで公開されているパッケージからインストールすることです。インストールと依存関係の管理が簡素化されるだけでなく、この方法では使用しているバージョンを明確に制御でき、新しいバージョンが公開されるたびに簡単に更新できます。

SDKは**セマンティックバージョニング（SemVer）**に従っており、patchおよびminorの更新では互換性を破壊する変更は導入されません。これらの更新を自動的に受け取るようにプロジェクトを構成しても安全です。統合の調整が必要になる可能性のある変更はmajorバージョンに限定され、常に移行ガイドが付属します。

SDKを最新の状態に保つ

最新バージョンを維持することは、2つの理由から特に重要です。1つ目はセキュリティです。脆弱性が特定されたとき、または通信プロトコルを強化する機会が生じたときには、必ずセキュリティパッチが公開されます。古いバージョンを使用することは、これらの修正を見送り、フローを不要なリスクにさらすことを意味します。2つ目は安定性です。バグ修正も同じ方法で配布され、古いバージョンには、より新しいリリースですでに解決済みの挙動が残っている可能性があります。

始める前に、Unicoのサポートチームにドメインを登録してください。すべてのドメインはHTTPSを使用する必要があります。

ステップ2: init(options)を呼び出す

SDKを初期化し、ジャーニーが正しく機能するために必要なスクリプトを事前に読み込み、エンドユーザーにより滑らかな体験を提供します。フローのできるだけ早い段階で呼び出してください。

パラメータ	必須	説明
token	はい	Create Process APIから返されるプロセストークン
env	いいえ	テスト環境の場合のみ'uat'を設定

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コールバックを呼び出します。そこから、アプリケーションはgetProcessAPIを呼び出して結果を確認するか、非同期のアプローチが望ましい場合は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') {
      // ジャーニー完了（transaction = { id, redirectUrl }）: ここで自身のフローを続行します。
    }
    // type === 'CLOSE' → ユーザーが完了前に閉じた;
  },
  // 任意: ウィジェットと重なる可能性のあるUIをアプリが表示する場合にのみ必要。
  onWidgetVisibilityChange: (visible) => {
    // ウィジェットの表示状態に応じてモーダルを非表示または復元する
  },
});

// SDKをいつでも明示的に閉じるには:
ByUnicoSDK.close();

以下のシーケンス図は、SDKとAPIの結果を使用してiFrameを構成する方法を示しています。

セキュリティ

このセクションの範囲

このセキュリティに関する論拠は、特にWeb App Integration（idpay-b2b-sdk）に適用されます。Web SDK（unico-webframe）は異なるモデルを使用しており、完全にページのコンテキスト内で動作し、CSPを必要とします。これらは、異なるセキュリティアーキテクチャを持つ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を閉じてください。

サポート対象外の統合

このドキュメントで説明されているモデル（直接アクセスとJourneys SDK）は、Unicoが公式にサポートする唯一の統合アプローチです。これらの標準から外れた統合は、予期しない動作、セキュリティフローの不具合、ジャーニーの中断を引き起こす可能性があり、Unicoのサポート対象外となります。

サポート対象外のアプローチの例:

• モバイルアプリでSDKをWebView内に埋め込むこと。これらの場合の正しいアプローチは、直接アクセスモデルを使用し、Journeys SDKを介さずにジャーニーのリンクをWebViewで直接開くことです。
• Journeys SDKを介さずに、HTMLの<iframe>タグでiFrameを直接読み込むこと。iFrameはSDKの内部実装の詳細であり、手動でインスタンス化してはなりません。正しいアプローチは、iFrameのライフサイクルを安全に、期待される標準の範囲内で管理するJourneys SDKを使用することです。

あるアプローチがサポート対象の標準の範囲内かどうか疑問がある場合は、実装を進める前にドキュメントを参照するか、サポートにお問い合わせください。