サイレント認証 - ベストプラクティス

SDKでWiFiをバイパスし、モバイルデータ接続を強制する

サイレント認証には、アクティブなモバイルデータ接続が必要です。リクエストがWi-Fi経由で行われた場合、エラーになります。ユーザーがWiFiを使用している場合でもリクエストが成功するように、Vonageはネイティブの iOS そしてアンドロイドモバイルデータ接続を強制するSDK。

SDKを使用することで、エッジケースにおけるUXの影響を最小限に抑えることもできます：

接続性チェック (例えば sdk_no_data_connectivity)を使用することで、より高速でシームレスなフェイルオーバーを実現することができます。
リダイレクト間のタイムアウト管理 低速のモバイルデータ環境下での待ち時間を短縮する。
iOS26対応 該当する市場（例えばスペイン）において。

さらに、Vonage SDKはHTTPリダイレクト（最大10）を処理し、タイムアウト（5秒、各リダイレクト後にリセット）を管理します。

リージョナル・エンドポイントを使用して待ち時間を短縮する

サイレント認証の待ち時間を改善するには、エンドユーザーの所在地に一致するVonage地域エンドポイントを使用することをお勧めします：

北米： api-us.vonage.com
ヨーロッパだ： api-eu.vonage.com
アジアだ： api-ap.vonage.com

リージョナルエンドポイントを使うことで、リクエストが可能な限り最短のパスでルーティングされるようになり、リダイレクトによる遅延を最小限に抑えることができます。

注：非リージョナル（グローバル）エンドポイントを使用すると、米国のトラフィックは米国を経由してルーティングされます。しかし、アジア太平洋（AP）からのトラフィックを含む他のすべてのトラフィックは、ヨーロッパを経由してルーティングされるため、遅延が増加する可能性があります。

フロントエンド

Verify内のサイレント認証は、ユーザーを認証するための簡単でわかりやすい方法を提示し、他のチャンネルと比較してより優れたユーザーエクスペリエンスを提供します。

新規アカウント作成ユースケースの場合、モバイルアプリケーションはエンドユーザーの電話番号を知らないため、ウェルカム画面の入力フィールドで電話番号を収集する必要があります。あるいは、すでにアカウントを持っていて、パスワードなしでログインしようとしているエンドユーザーは、すでに電話番号が保存されています。この場合、エンドユーザーにはあらかじめ入力済みのテキストフィールドが表示され、必要なアクションは「Verify」を選択することだけである。

Silent Authentication（サイレント認証）を体験している間、ユーザがそのプロセスに慣れ、認証プロセスがバックグラウンドで実行されていることを認識できるようにする。

進行中の状態

認証がバックグラウンドで実行されている間に期待値を設定するには、以下の方法を推奨する：

エンドユーザが、モバイルアプリケーションが認証タスクに取り組んでいることを認識できるように、スピニングホイールまたは同様のフィードバックメカニズムを提示する。
あるいは、同じローディングインジケーターと追加テキストを表示した専用画面を表示する。

成功への道

Silent Authenticationが正常に完了すると、ユーザーはコードを入力する必要なく、明確な成功状態に移行する。

フォールバック・パス

サイレント認証フロー中に障害が発生した場合、ユーザがピンコードを挿入して2FAプロセスを完了できるように、アプリケーションフロントエンドを調整する必要がある。このコードは、フェイルオーバー・チャネルを介して配信される。

要約すると、下図は両方のユーザージャーニーを示している。 成功の道 (サイレント認証はバックグラウンドで完了します）と フォールバックパス (ユーザはフェイルオーバーコードを入力するよう促される）。

サイレント認証におけるエラーとタイムアウトの処理

サイレント認証は、その性質上、モバイルデータ接続の欠如やネットワークの一時的な中断など、外部の状況によって影響を受ける可能性があります。スムーズなユーザーエクスペリエンスを保証するために、モバイルアプリはクライアント・ライブラリー独自のネットワークチェックやタイムアウト管理を実装するのではなく、例外処理を内蔵している。

SDKは問題が発生すると、何が問題であったかを示す特定の例外をスローします。例えば sdk_no_data_connectivityモバイルデータ接続が利用できない場合にスローされる。

モバイルデータなしでサイレント認証の開始を避ける

サイレント認証リクエストを開始する前に、クライアント・ライブラリモバイル通信の事前チェックを明示的に実行するため。SDKがモバイルデータ通信が利用できない状態（例えば、デバイスがWi-Fiのみの接続状態である、または電波が受信できないなど）を検出した場合、以下を返します。 false (iOS) または CellularStatus.Unavailable (Android)。アプリではこの結果を確認し、フォールバックチャネルに進む必要があります。これにより、不要なリクエストの試行を回避し、検証にかかる総時間を短縮できます。実装の詳細については、 iOS クライアントライブラリの README または Android クライアントライブラリの README.

事前チェックに失敗した場合は、サイレント認証チャネルをスキップする必要があります。その場合でも、バックエンドは引き続き POST /v2/verify、ただし、サイレント認証チャネルは使用せず、選択したフォールバックチャネル（SMS、RCS、音声など）のみを使用して行う必要があります。この場合、 check_url が返され、 next_workflow フォールバックチャネルが直接起動されるため、これは不要です。

注: 「Verify」リクエストの作成後に接続の問題が発生した場合（たとえば、読み込み中にネットワークが切断された場合など） check_url)、SDKは次のような例外をスローすることがあります。 sdk_no_data_connectivity. この場合、返された request_id そして next_workflow バックエンドから直ちに。詳細はこちらをご覧ください。タイムアウトの動作詳細はこちら。

タイムアウトの動作

アプリはこれらの例外をキャッチし、バックエンドに next_workflow エンドポイントを直ちに削除する。これにより、サイレント認証ワークフローが失敗したり、続行できなくなったりした場合でも、検証フローが優雅に継続される。

モバイルアプリが次のワークフローに移行するアクションを取らない場合、システムは60秒後に自動的にタイムアウトし、次のワークフローに進みます。

以下のシーケンス図は、2つの障害シナリオを示しています：(1) SDKの事前チェックでモバイルデータが利用できないことが検出された場合 — サイレント認証はスキップされます（したがって、 check_url が返される）、および（2）Verifyリクエストは正常に作成されたものの、モバイルアプリが読み込み中にリダイレクトフローを完了できなかった場合 check_url （例えば、ネットワークの問題などによる場合）：

推奨フロー

サイレント認証を開始する前に、SDKの事前チェックメソッドを明示的に呼び出して、モバイル通信の接続状態を確認してください。実装の詳細については、 iOS クライアントライブラリの README または Android クライアントライブラリの README.
事前チェックの結果が false (iOS) または CellularStatus.Unavailable (Android)の場合、サイレント認証チャネルはスキップしてください。バックエンドからは引き続き POST /v2/verify、……だが、そうすべきだ サイレント認証チャネルを使用しない場合 — 選択したフォールバックチャネル（SMS、RCS、音声など）のみを使用します。この場合、 check_url が返され、 next_workflow フォールバックチャネルが直接起動されるため、これは不要です。
事前チェックに合格した場合は、サイレント認証を開始し、リクエストを送信します。 check_url バックエンド経由で (POST /v2/verify).
バックグラウンドでサイレント認証が完了するまで待ちます。成功した場合は、認証済み状態に進みます。
Verifyリクエストの作成後に例外が発生した場合（たとえば、読み込み中に check_url), それをキャッチして、バックエンドを呼び出してトリガーする next_workflow (必要条件： request_id).
アプリの内部タイムアウト（例えば、デフォルトの60秒前）内にレスポンスやコールバックを受け取らなかった場合、以下を呼び出す。 next_workflow も同様だ。

このアプローチは、待ち時間を最小限に抑え、ユーザーエクスペリエンスを向上させ、バックエンドが常にワークフローの正しいステップに進むようにします。

`next_workflow` 再試行の動作

いつ next_workflow サイレント認証の設定がまだ完了していない段階でこのメソッドが呼び出された場合、Verifyはそのイベントをキューに入れ、短い時間枠内で内部的に再試行を行います。

サイレント認証の起動に異常に時間がかかる場合、および next_workflow フローの非常に早い段階で呼び出されると、再試行の有効期限が切れてしまう可能性があります。その場合、API は HTTP 409 Conflict エラーを返し、再試行するよう指示します：

{
  "type": "https://developer.vonage.com/en/api-errors/verify-v2#conflict",
  "title": "Conflict",
  "detail": "The operation cannot be performed at this time. Please try again later.",
  "instance": "my-trace-id-trigger-next-replication-delay"
}

フェイルオーバーのシナリオ

このセクションでは、サイレント認証リクエスト中に発生する可能性のあるすべてのシナリオを列挙し、最高のエンドユーザー・エクスペリエンスを確保するためのフェイルオーバー実装についてアドバイスする。

シナリオによっては、次のチャネルへのフェイルオーバーが即座にトリガーされますが、フェイルオーバーがデフォルトのサイレント認証のタイムアウト（60秒）後にのみトリガーされる場合もあります。さまざまな障害シナリオをまとめた以下の表を参照してください：

シナリオ	故障理由	故障コード	故障の対応	即時フェイルオーバー？
1	サイレント認証エラー	HTTP 409	`{ "title": "Silent Auth error", "detail": "The Silent Auth request could not be completed due to formatting or the carrier is not supported."}`	はい
2	MSISDNエラー	HTTP 409	`{ "title": "MSISDN Error", "detail": "Device MSISDN does not match."}`	はい
3	ネットワークがサポートされていない	HTTP 412	`{ "title": "Network not supported", "detail": "Device number does not resolve to a supported Mobile Network Operator."}`	はい
4	IPエラー	HTTP 412	`{ "title": "IP Error", "detail": "IP Address does not resolve to a cellular device."}`	はい
5	iOS/Android SDKエラー	--	`sdk_no_data_connectivity`, `sdk_connection_error`, `sdk_redirect_error`, `sdk_error`	いいえ
6	`next_workflow` 「サイレント認証」の設定中に、受信が早すぎた	HTTP 409	`{ "title": "Conflict", "detail": "The operation cannot be performed at this time. Please try again later."}`	いいえ

サイレント認証課金

Silent Authentication要求が開始されると、Verifyプラットフォーム料金のエントリが1つ生成され、 Silent Authenticationの使用量を示すエントリが1つまたは2つ追加される。としてマークされたエントリが生成される。 INITIATED が請求されることはない。合計で、1 つの Silent Authentication リクエストは、最大 3 つの関連レコードを持つことができる。

テスト

Verifyサイレント認証をテストするには、次のようにします：

用途バーチャルナンバー.
サポートされているネットワークの Numbers をリストアップできます。ネットワーク・レジストリ.

顧客がライブトラフィックを送信する必要がある場合は、以下の方法で携帯電話会社に登録する必要がある。ネットワーク・レジストリ.