モバイル H5 ページ経由で FACE_LIVENESS に接続する - ID Verification

ID Verification - KYC は、ブラウザまたは WebView で顔の収集とライブネス検証を実装するために使用できる Web SDK を提供します。 KYC は Know Your Customer の略です。このトピックでは、モバイル H5 ページ経由で ID Verification - KYC の FACE_LIVENESS ソリューションに接続する方法について説明します。

前提条件

最小オペレーティングシステムバージョン: Android 5 以降および iOS 11 以降。
対応ブラウザ:
- iOS: Safari を推奨します。 iOS 14.3 以降では、Google Chrome、Mozilla Firefox、Microsoft Edge、および Apple WKWebView がサポートされています。
- Android: Chrome 60 以降および Firefox 58 以降を推奨します。対応ブラウザはデバイスによって異なります。
必要な権限: ネットワークとカメラ。メディア収集には HTTPS デプロイメントが必要です。
縦モード: 横モードではページのインタラクションに問題が発生する可能性があります。ページに表示される指示に従って、ユーザーに縦モードを使用して検証を行うように案内することをお勧めします。
互換性: ブラウザの互換性の断片化の問題があるため、プロセス設計で、推奨されるブラウザを使用して検証を行うようにユーザーに案内することをお勧めします。
このソリューションをモバイルアプリに統合する場合、埋め込みブラウザが原因で互換性の問題が発生する可能性があります。互換性の問題を軽減するか、Native SDK を統合するには、アプリ内統合のための H5 モバイル SDK 互換性構成を参照できます。

重要

統合プロセス中に、パラメータ値の変更など、TransactionUrl パラメータに対する操作を実行しないでください。統合プロセス中に TransactionUrl に対して操作を実行すると、検証例外が発生します。
安全で効果的な検証を確保するために、検証 URL は一度だけ使用できます。 URL を再利用するとエラーが発生します。

FACE_LIVENESS の開始

コードに次の JavaScript ファイルをインポートし、getMetaInfo() 関数を呼び出して MetaInfo を取得します。

<script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/jsvm_all.js" ></script>

説明

ID Verification - KYC の検証操作を呼び出すときは、戻り値を MetaInfo パラメータに渡す必要があります。

独自のビジネスサーバー API を呼び出して初期化し、TransactionUrl を取得し、検証のためにこのリンクをブラウザにロードします。

サンプルコード

<!DOCTYPE HTML>
<html lang="en">
  <head>
    <title>Title</title>
        <!--   JavaScript ファイルを追加し、getMetaInfo 関数をグローバルに挿入します。   -->
        <!--   JavaScript ファイルを追加し、getMetaInfo 関数をグローバルに挿入します。   -->
    <script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/jsvm_all.js" ></script>
  </head>
  <body>
  <div></div>
    <script>
      // 初期化操作を呼び出すときにメタ情報を渡します。
      var MetaInfo = window.getMetaInfo();

      // 初期化操作を呼び出して TransactionUrl パラメータを取得します。
      var TransactionUrl = ''; // 値は初期化操作によって返されます。

      // TransactionUrl パラメータで指定された URL にアクセスして検証を開始します。
      window.location.href = TransactionUrl;
    </script>
  </body>
</html>

クライアント側カスタム構成

ID Verification Web SDK は、TransactionUrl でパラメータを渡すことにより、クライアント側カスタム機能をサポートします。

& 文字を使用してTransactionUrl にパラメータを追加することで、構成を適用できます。次の例は、その方法を示しています。

TransactionUrl:

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc

initTimeout を追加する:

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc&initTimeout=30

サポートされている機能は、次の表にリストされています。

パラメータ	タイプ	必須	説明	例
initTimeout	String	いいえ	クライアント側検証の初期化のタイムアウト期間 (秒単位)。これは、ページの読み込み開始から顔または OCR ページが表示されるまでの時間です。	30
clientLivenessTimeout	String	いいえ	1 回の顔のライブネス検知のタイムアウト期間 (秒単位)。	30
clientLivenessRetryCount	String	いいえ	顔のライブネス検知の再試行回数。	5
ocrTimeout	String	いいえ	1 回の OCR 検知のタイムアウト期間 (秒単位)。	20
ocrRetryCount	String	いいえ	OCR の再試行回数。	10
region	String	いいえ	モバイルクライアントが Alibaba Cloud に API リクエストを送信するリージョン。次のコードは、region 値とリージョンのマッピングを示しています。 `{ "HK": "Hong Kong", "US": "US East", "US-CA": "US West", "SG": "Singapore", "MY": "Malaysia", "ID": "Indonesia", "PH": "Philippines", "DE": "Germany", "SA": "Saudi Arabia" }` 説明このパラメータを渡して、Alibaba Cloud API を呼び出すためのサービスリージョンを指定します。このパラメータを指定しない場合、デフォルトで最も近いリージョンにアクセスします。	HK

レスポンスの解析

サーバー側リクエストの初期化中に ReturnUrl パラメータが渡されると、これは加盟店定義のパラメータとして機能します。認証が完了すると、認証結果はパラメータとして ReturnUrl に追加され、加盟店に返されます。レスポンスの解析結果は、受信ルーティングモードによって異なります。

ルーティングモード	ReturnUrl の例	検証後の ReturnUrl の例
一般的な Web ページ	https://aliyundoc.com	https://aliyundoc.com/？response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
一般的な Web ページ	https://aliyundoc.com/index.html	https://aliyundoc.com/index.html?response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
ページアンカー (#) がない履歴ルーティング	https://aliyundoc.com/xxx/	https://aliyundoc.com/xxx?response=%7B%22resultCode%22%3A%22%22%2C%22resultMessage%22%3A%22%22%2C%22ocrResult%22%3A%7B%22code%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%2C%22faceResult%22%3A%7B%22code%22%3A%22%22%2C%22subCode%22%3A%22%22%2C%22reason%22%3A%22%22%2C%22extInfo%22%3A%7B%22certifyId%22%3A%22%22%7D%7D%7D
ページアンカー (#) がある履歴ルーティング	https://aliyundoc.com/xxx/#xxx	https://aliyundoc.com/xxx?response=%257B%2522resultCode%2522%253A%2522%2522%252C%2522resultMessage%2522%253A%2522%2522%252C%2522ocrResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%252C%2522faceResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%257D#xxx
ハッシュルーティング	https://aliyundoc.com/#/aaa/bbb	https://aliyundoc.com/?response=%257B%2522resultCode%2522%253A%2522%2522%252C%2522resultMessage%2522%253A%2522%2522%252C%2522ocrResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%252C%2522faceResult%2522%253A%257B%2522code%2522%253A%2522%2522%252C%2522subCode%2522%253A%2522%2522%252C%2522reason%2522%253A%2522%2522%252C%2522extInfo%2522%253A%257B%2522certifyId%2522%253A%2522%2522%257D%257D%257D/#/aaa/bbb

レスポンスを解析するためのサンプルコード

一般的な Web ページ

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // window.location.href を構成します。
            // window.location.href = https://aliyundoc.com
            // または
            // window.location.href = https://aliyundoc.com/index.html

            // URL オブジェクトを初期化します
            var url = new URL(window.location.href);
            // レスポンスを解析します
            var response = JSON.parse(url.searchParams.get('response'));
            // response = {
            //     resultCode: '',
            //     resultMessage: '',
            //     ocrResult: {code: '',reason: '', extInfo: {certifyId: ''}},
            //     faceResult: {code: '',subCode: '',reason: '', extInfo: {certifyId: ''}}
            // }
        </script>
    </body>
</html>

ページアンカー (#) がない履歴ルーティング

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // window.location.href を構成します。
            // window.location.href = https://aliyundoc.com/xxx

            // URL オブジェクトを初期化します
            var url = new URL(window.location.href);
            // レスポンスを解析します
            var response = JSON.parse(url.searchParams.get('response'));
            // response = {
            //     resultCode: '',
            //     resultMessage: '',
            //     ocrResult: {code: '',reason: '', extInfo: {certifyId: ''}},
            //     faceResult: {code: '',subCode: '',reason: '', extInfo: {certifyId: ''}}
            // }
        </script>
    </body>
</html>

ページアンカー (#) がある履歴ルーティング

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // window.location.href を構成します。
            // window.location.href = https://aliyundoc.com/xxx/#xxx

            // URL オブジェクトを初期化します
            var url = new URL(window.location.href);
            // レスポンスを解析します
            var response = JSON.parse(
                decodeURIComponent(url.searchParams.get('response'))
            );
            // response = {
            //     resultCode: '',
            //     resultMessage: '',
            //     ocrResult: {code: '',reason: '', extInfo: {certifyId: ''}},
            //     faceResult: {code: '',subCode: '',reason: '', extInfo: {certifyId: ''}}
            // }
        </script>
    </body>
</html>

ハッシュルーティング

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Title</title>
    </head>
    <body>
        <script>
            // window.location.href を構成します。
            // window.location.href = https://aliyundoc.com/#/aaa/bbb

            // URL オブジェクトを初期化します
            var url = new URL(window.location.href);
            // レスポンスを解析します
            var response = JSON.parse(
                decodeURIComponent(url.searchParams.get('response'))
            );
            // response = {
            //     resultCode: '',
            //     resultMessage: '',
            //     ocrResult: {code: '',reason: '', extInfo: {certifyId: ''}},
            //     faceResult: {code: '',subCode: '',reason: '', extInfo: {certifyId: ''}}
            // }
        </script>
    </body>
</html>

クライアントカスタム構成

ID Verification Web SDK 統合メソッドでは、TransactionUrl で渡されるパラメータを使用してクライアント側をカスタマイズできます。次の表は、サポートされている機能を示しています。

パラメータ名	タイプ	必須	説明	値の例
initTimeout	String	いいえ	クライアント認証の初期化タイムアウト (ページの読み込みから顔/ OCR ページに入るまでの時間) (秒単位)。	30
clientLivenessTimeout	String	いいえ	顔のライブネス検知の単一タイムアウト (秒単位)。	30
region	String	いいえ	モバイル Alibaba Cloud インターフェースリクエストリージョンのエントリポイント。リージョン値とリージョンのマッピングは次のとおりです。説明このパラメータを渡すと、Alibaba Cloud インターフェースを呼び出すためのサービスリージョンが指定されます。指定しない場合、システムはデフォルトで最も近いリージョンにアクセスします。 `{ "HK": "Hong Kong", "US": "US East", "US-CA": "US West", "SG": "Singapore", "MY": "Malaysia", "ID": "Indonesia", "PH": "Philippines", "DE": "Germany", "SA": "Saudi Arabia" }`	HK

& を使用してTransactionUrl にパラメータを追加することで、構成を有効化できます。例は次のとおりです。

TransactionUrl: https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc
initTimeout を追加するには、https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc&initTimeout=30 を使用します。

クライアント側の結果コード

結果コード	課金対象	説明
1000	はい	ユーザーは顔認証プロセスを完了し、推奨される認証結果は合格です。この結果は参考値です。 CheckResult 操作を呼び出して最終的な認証結果を取得し、さらに処理することができます。
1001	はい	ユーザーは顔認証プロセスを完了し、推奨される認証結果は不合格です。この結果は参考値です。 CheckResult 操作を呼び出して最終的な認証結果を取得し、さらに処理することができます。
1002	いいえ	システムエラーが発生しました。
1003	いいえ	SDK の初期化に失敗しました。クライアント時刻が有効かどうかを確認してください。
1004	いいえ	カメラエラーが発生しました。エラーを修正するには、次の操作を実行します。認証前に、アプリにカメラの権限があるかどうかを確認します。アプリにカメラの権限があるにもかかわらず権限なしエラーが続く場合は、アプリのキャッシュをクリアして再試行してください。
1005	いいえ	ネットワークエラーが発生しました。
1006	いいえ	顧客が予期せず終了しました。
1007	いいえ	トランザクション ID が無効です。
1009	いいえ	クライアントのタイムスタンプが無効です。
1011	いいえ	指定されたドキュメントタイプが送信されたドキュメントと一致しません。
1012	いいえ	ドキュメント検証後に重要な情報が欠落しているか、形式検証に失敗しました。
1013	いいえ	画質が要件を満たしていません。
1014	いいえ	エラー数が上限を超えています。