Web および H5 クライアント用の V2 アーキテクチャを統合する -

コンソールで検証シナリオを追加した後、検証が必要な Web または H5 ページに Captcha の初期化コードを統合する必要があります。このトピックでは、このクライアント側の統合を実行する方法について説明します。

前提条件

Alibaba Cloud Captcha 2.0 を有効化していること。
Integration Method が [Web/][H5] に設定されている検証シナリオを作成していること。

V2 検証アーキテクチャのシーケンス図

スライダー、パズル、クリック、およびイメージ復元検証

シーケンス図の説明：

クライアントは Captcha を初期化し、Captcha サーバーにリクエストを送信して、イメージや質問などのリソースを取得します。
リクエストが失敗した場合、クライアントが受信したエラーメッセージを確認して原因を特定し、問題を解決できます。
ユーザーはウェブページで Captcha のインタラクション (スライダー、パズル、クリック、またはイメージ復元など) とビジネスインタラクション (ログインや登録など) を完了します。
インタラクションが完了すると、クライアントは Captcha パラメーターとビジネスパラメーターをビジネスサーバーに送信します。
ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために Captcha サーバーに検証リクエストを送信します。
Captcha サーバーは脅威レベルを判断し、検証結果をビジネスサーバーに返します。
ビジネスサーバーは、そのビジネスロジックに基づいてリクエストを処理します。処理が完了すると、検証結果とビジネス処理結果をクライアントに返します。
クライアントページはプロンプトを表示し、ビジネスリクエストを処理します。
検証に失敗した場合、Captcha はリフレッシュされ、プロセスはステップ 1 に戻ります。

インタラクションなしの検証

シーケンス図の説明：

クライアントは Captcha を初期化し、Captcha サーバーにリクエストを送信して、イメージや質問などのリソースを取得します。
リクエストが失敗した場合、クライアントが受信したエラーメッセージを確認して原因を特定し、問題を解決できます。
ユーザーはクライアントでログインや登録などのビジネスインタラクションを完了します。
インタラクションが完了すると、クライアントはインタラクションなしの検証パラメーターとビジネスパラメーターをビジネスサーバーに送信します。
ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために Alibaba Cloud サーバーに検証リクエストを送信します。
Alibaba Cloud サーバーは脅威レベルを判断し、検証結果をビジネスサーバーに返します。
ビジネスサーバーは、そのビジネスロジックに基づいてリクエストを処理します。
- ユーザーにリスクがない場合、検証プロセスは終了します。
- ユーザーにリスクがある場合、二次認証がトリガーされます。
  1. ユーザーはウェブページで Captcha のインタラクション (スライダー、パズル、クリック、またはイメージ復元など) とビジネスインタラクション (ログインや登録など) を完了します。
    インタラクションが完了すると、クライアントは Captcha パラメーターとビジネスパラメーターをビジネスサーバーに送信します。
  2. ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために Alibaba Cloud サーバーに検証リクエストを送信します。
  3. Alibaba Cloud サーバーは脅威レベルを判断し、検証結果をビジネスサーバーに返します。
  4. ビジネスサーバーは、そのビジネスロジックに基づいてリクエストを処理します。処理が完了すると、検証結果とビジネス処理結果をクライアントに返します。
  5. クライアントページはプロンプトを表示し、ビジネスリクエストを処理します。
    検証に失敗した場合、クライアントページは Captcha を再初期化し、プロセスはステップ i に戻ります。

Captcha 初期化コードの統合

Web および H5 ページは、ポップアップモードと埋め込みモードをサポートしています。このセクションでは、ログインシナリオを例として、Captcha コードをクライアントのソースコードに統合する方法について説明します。

クライアントのソースコードで、Captcha 用のページ要素を予約します。この要素は、element および button パラメーターによって参照される DOM 要素です (次の例の <div id="captcha-element"></div> など)。Captcha タイプを切り替えるときに Captcha の高さが変更された場合に Captcha 要素がコンテナーの高さを超えないように、ビジネスモジュールコンテナーの高さをアダプティブに設定することをお勧めします。

重要

統合後、コンソールでシナリオ構成 (Captcha モードなど) を変更した場合、初期化パラメーターやページ構造を調整する必要はありません。プログラムは必要に応じて新しい構成をロードします。

// 元のクライアントコードの例
 const button = document.getElementById('button');
 button.onclick = function () {
   // バックエンド API をリクエスト...
   const result = await getWithParams('xx', { 
       yourBizParam... // ビジネスパラメーター
   });                
   const { bizResult } = result;
   if (bizResult) {
     // 対応するページにリダイレクトします。この例では、ページは https://www.aliyun.com/ です。
     window.location.href = 'https://www.aliyun.com/';
   }
 }

// クライアント本文のコード
<div id="space-semantic">
    <div id="embed-wrapper">
        <h2>Pop-up</h2>
        <div class="embed-wrapper">
            <div>
                <label>Username:</label>
                <input id="username-embed" class="biz-input">
            </div>
            <div>
                <label>Password:</label>
                <input id="password-embed" type="password" class="biz-input">
            </div>
            <div id="captcha-element"></div>  // Captcha 用に予約されたページ要素。初期化関数で element パラメーターを構成するために使用されます
            <button id="button" class="login-btn">Log on</button>
        </div>
    </div>
</div>

グローバル変数と Captcha JS スクリプトを含む Captcha 初期化コードを統合します。Alibaba Cloud Captcha JS スクリプトをインポートする前、または HTML ファイルの head タグの先頭に、AliyunCaptchaConfig という名前のグローバル変数を定義するスクリプトを追加します。この変数には、region および prefix パラメーターが含まれます。

重要

Captcha JS を動的にインポートする必要があります。JS コードをプルしてローカルにデプロイするなど、動的ロードを回避する他の方法を使用すると、Captcha は期待どおりに更新されません。これにより、セキュリティが損なわれたり、誤ったブロックが発生したり、互換性の問題が発生したりする可能性があります。
より完全な環境およびデバイス情報を収集するために、できるだけ早く Captcha JS をロードしてください。Captcha JS のロードから検証リクエストの送信までの間隔は 2 秒より長くする必要があります。
イメージリソースのより高速なロードを保証するために、できるだけ早く Captcha を初期化してください。初期化から検証リクエストの送信までの間隔は 2 秒より長くする必要があります。これにより、Captcha 関連のリソースがロードされ、イメージのロードが高速化されます。
初期化パラメーターが変更された場合など、必要なシナリオを除き、initAliyunCaptcha メソッドを繰り返し呼び出さないでください。

ポップアップ

<!doctype html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="data-spm" />
        <!--1. Alibaba Cloud Captcha JS スクリプトをインポートする前、または HTML ファイルの head タグの先頭に、region および prefix パラメーターを含む AliyunCaptchaConfig という名前のグローバル変数を保存するスクリプトを追加します。-->
        <script>
            window.AliyunCaptchaConfig = {
                // 必須。Captcha インスタンスが存在するリージョン。有効な値: cn (中国本土) および sgp (シンガポール)。
                region: "cn",
                // 必須。ID 認証情報。Alibaba Cloud Captcha 2.0 を有効化すると、コンソールの [概要] ページにある [インスタンスの基本情報] カードで ID 認証情報を取得できます。
                prefix: "xxxxxx",
            };
        </script>
        <!--2. メイン JS を統合します。-->
        <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js">
        </script>
    </head>
    
    <body>
        <!--3. <script> タグを作成して、Captcha 初期化関数 initAliyunCaptcha を呼び出します。-->
        <script type="text/javascript">
            var captcha;
            // ポップアップモードのパラメーター (region と prefix を除く)
            window.initAliyunCaptcha({
                // シナリオ ID。ステップ 2 で検証シナリオを作成した後、検証シナリオリストからシナリオ ID を取得できます。
                SceneId: 'c9h3****',
                // Captcha モード。popup は Captcha がポップアップモードであることを示します。このパラメーターを変更する必要はありません。
                mode: 'popup',
                // Captcha をレンダリングするためにページ上に予約された要素。これは、元のコードで予約されたページ要素と同じでなければなりません。
                element: '#captcha-element',
                // Captcha ポップアップウィンドウをトリガーする要素。button は、ログインボタンをクリックした後に captchaVerifyCallback 関数がトリガーされることを示します。使用する要素に基づいて element の値を変更できます。
                button: '#button',
                // Captcha 検証を伴うビジネスリクエストのコールバック関数。このパラメーターを変更する必要はありません。
                captchaVerifyCallback: captchaVerifyCallback,
                // ビジネスリクエスト結果のコールバック関数。このパラメーターを変更する必要はありません。
                onBizResultCallback: onBizResultCallback,
                // Captcha インスタンスをバインドする関数。このパラメーターを変更する必要はありません。
                getInstance: getInstance,
                // スライダー Captcha のスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。最小幅は 320 px です。
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // Captcha の言語。有効な値: cn (簡体字中国語)、tw (繁体字中国語)、en (英語)。
                language: 'cn',
            });
            function getInstance(instance) {
                captcha = instance
            }
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1. バックエンドにビジネスリクエストを送信して、Captcha 検証結果とビジネス結果を取得します。
                const result = await xxxx('http://Your business request address', {
                    // Captcha パラメーター
                    captchaVerifyParam: captchaVerifyParam,
                   // ビジネスパラメーター
                    yourBizParam... 
                });

                // 2. 標準の戻りパラメーターを構築します。
                const verifyResult = {
                    // Captcha 検証が成功したかどうかを指定します。このパラメーターはブール型で、必須です。
                    captchaResult: result.captchaVerifyResult,
                    // ビジネス検証が成功したかどうかを指定します。このパラメーターはブール型で、オプションです。ビジネス検証結果がない場合は、bizResult を空のままにすることができます。
                    bizResult: Obtain your business verification result from the result,

                };
                return verifyResult;
            }

            // ビジネスリクエスト検証結果のコールバック関数
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // ビジネス検証が成功した場合、対応するページにリダイレクトされます。この例では、ページは https://www.aliyun.com/ です。
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // ビジネス検証が失敗した場合、失敗メッセージが返されます。この例では、メッセージは「ビジネス検証に失敗しました！」です。
                    alert('Business verification failed!');
                }
            }
        </script>
    </body>
</html>

埋め込み

<!doctype html>
<html>
    
    <head>
        <meta charset="utf-8" />
        <meta name="data-spm" />
        <!-- 1. Alibaba Cloud Captcha JS スクリプトをインポートする前、または HTML ファイルの head タグの先頭に、region および prefix パラメーターを含む AliyunCaptchaConfig という名前のグローバル変数を保存するスクリプトを追加します。
        -->
        <script>
            window.AliyunCaptchaConfig = {
                // 必須。Captcha インスタンスが存在するリージョン。有効な値: cn (中国本土) および sgp (シンガポール)。
                region: "cn",
                // 必須。ID 認証情報。Alibaba Cloud Captcha 2.0 をアクティブ化した後、コンソールの [概要] ページの [インスタンスの基本情報] カードで ID 認証情報を取得できます。
                prefix: "xxxxxx",

            };
        </script>
        <!-- 2. メイン JS を統合します。 -->
        <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js">
        </script>
    </head>
    
    <body>
        <!-- 3. <script> タグを作成して、Captcha 初期化関数 initAliyunCaptcha を呼び出します。 -->
        <script type="text/javascript">
            var captcha;
            // 埋め込みモードのパラメーター (region と prefix を除く)
            window.initAliyunCaptcha({
                // シナリオ ID。ステップ 1 で検証シナリオを作成した後、検証シナリオリストからシナリオ ID を取得できます。
                SceneId: 'c9h3****',
                // Captcha モード。embed は、Captcha が埋め込みモードであることを示します。このパラメーターを変更する必要はありません。
                mode: 'embed',
                // Captcha をレンダリングするためにページ上で予約されている要素。これは、元のコードで予約されているページ要素と同じである必要があります。
                element: '#captcha-element',
                // ビジネスリクエストをトリガーする要素。button は、ログインボタンをクリックした後に captchaVerifyCallback 関数がトリガーされることを示します。使用する要素に基づいて element の値を変更できます。
                button: '#button',
                // Captcha 検証を伴うビジネスリクエストのコールバック関数。このパラメーターを変更する必要はありません。
                captchaVerifyCallback: captchaVerifyCallback,
                // ビジネスリクエストの結果のコールバック関数。このパラメーターを変更する必要はありません。
                onBizResultCallback: onBizResultCallback,
                // Captcha インスタンスをバインドする関数。このパラメーターを変更する必要はありません。
                getInstance: getInstance,
                // スライダー Captcha のスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。最小幅は 320 px です。
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // Captcha の言語。有効な値: cn (簡体字中国語)、tw (繁体字中国語)、en (英語)。
                language: 'cn',
                // 検証完了後、すぐに検証リクエスト (captchaVerifyCallback 関数の呼び出し) を送信するかどうかを指定します。
                immediate: false,
            });

            // Captcha インスタンスをバインドする関数。これは固定式であり、変更する必要はありません。
            function getInstance(instance) {
                captcha = instance;
            }

            // Captcha 検証を伴うビジネスリクエストのコールバック関数
            /**
              * @name captchaVerifyCallback
              * @function
              * リクエストパラメーター: Captcha スクリプトによって返される検証パラメーター。このパラメーターをプロセスする必要はありません。サーバーに直接渡すことができます。
              * @params {string} captchaVerifyParam
              * 戻り値パラメーター: フィールド名は固定です。captchaResult は必須です。ビジネス検証シナリオが利用できない場合、bizResult はオプションです。
              * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}}
              */
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1. バックエンドにビジネスリクエストを送信して、Captcha 検証結果とビジネス結果を取得します。
                const result = await xxxx('http://Your business request address', {
                    // Captcha パラメーター
                    captchaVerifyParam: captchaVerifyParam,
                    // ビジネスパラメーター
                    yourBizParam... 
                });

                // 2. 標準の戻り値パラメーターを構築します。
                const verifyResult = {
                    // Captcha 検証に合格したかどうかを指定します。このパラメーターはブール型で、必須です。
                    captchaResult: result.captchaVerifyResult,
                    // ビジネス検証に合格したかどうかを指定します。このパラメーターはブール型で、オプションです。ビジネス検証結果が利用できない場合は、bizResult を空のままにすることができます。
                    bizResult: 結果からビジネス検証結果を取得します,

                };
                return verifyResult;
            }

            // ビジネスリクエストの検証結果のコールバック関数
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // ビジネス検証に合格した場合、対応するページにリダイレクトされます。この例では、ページは https://www.aliyun.com/ です。
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // ビジネス検証が失敗した場合、失敗メッセージが返されます。この例では、メッセージは「Business verification failed!」です。
                    alert('ビジネス検証に失敗しました！');
                }
            }
        </script>
    </body>

</html>

captchaVerifyCallback 関数は ES6 構文を使用します。ES5 構文を使用するには、次の例を参照してください。captchaVerifyCallback の 2 番目のパラメーター (コールバック関数) を呼び出し、検証結果を渡します。

/**
 * @name captchaVerifyCallback
 * @function
 * @param {String} captchaVerifyParam - Captcha スクリプトによって返される検証パラメーター。このパラメーターを処理する必要はありません。サーバーに直接渡すことができます。
 * @param {Function} callback - 検証結果を処理するために使用されるコールバック関数。ES5 構文と互換性があります。
 */
function captchaVerifyCallback(captchaVerifyParam, callback) {
  // 1. バックエンドにビジネスリクエストを送信して、Captcha 検証結果とビジネス結果を取得します。
  requestVerifyResult('http://Your business request address', { 
      captchaVerifyParam: captchaVerifyParam, // Captcha パラメーター
      yourBizParam... // ビジネスパラメーター
  }, function(result) {
      // 2. 標準の戻りパラメーターを構築します。
      var verifyResult = {
          captchaResult: result.captchaVerifyResult,
          bizResult: result.bizResult,
      };    
      // コールバック関数を呼び出し、検証結果を渡します。
      callback(verifyResult);
  });
}

統合中に質問がある場合は、チケットを送信してください。

パラメーター

AliyunCaptchaConfig パラメーター

パラメーター

タイプ

必須

デフォルト値

説明

region

文字列

はい

Captcha インスタンスが存在するリージョン。有効な値:

cn: 中国本土。
sgp: シンガポール。

重要

クライアント統合の region パラメーターがサーバー統合のエンドポイントと異なる場合、検証リクエストはエラーを返します。
このプロダクトには、中国本土 (中国 (上海)) とシンガポールにコントロールプレーンがあります。顧客が構成した呼び出しパラメーターに基づいて、クライアントが収集した行動データとデバイスデータは、対応するセンターに送信されて処理されます。これは主にセキュリティ認証を実装するためです。

prefix

文字列

はい

なし

Captcha の ID 認証情報。Captcha 2.0 を有効化した後にこの値を取得できます。

initAliyunCaptcha パラメーター

パラメーター	タイプ	必須	デフォルト値	説明
SceneId	文字列	はい	なし	Captcha のシナリオ ID。検証シナリオを作成した後にこの値を取得できます。
mode	文字列	はい	なし	Captcha モード。オプション: popup: ポップアップ。 embed: 埋め込み。重要インタラクションなしの検証は埋め込みモードをサポートしていません。統合にはポップアップモードを使用してください。
element	文字列	はい	captcha-element	Captcha をレンダリングするためにページ上に予約された要素。これは、ソースコードで予約されたページ要素と同じでなければなりません。
button	文字列	はい	なし	Captcha ポップアップウィンドウをトリガーする要素。値は、クライアント本文の button パラメーターの値と同じでなければなりません。
captchaVerifyCallback	関数	はい	captchaVerifyCallback	Captcha 検証を伴うビジネスリクエストのコールバック関数。詳細については、「captchaVerifyCallback」をご参照ください。
onBizResultCallback	関数	はい	onBizResultCallback	ビジネスリクエスト結果のコールバック関数。検証結果を処理するロジックを設定するために使用されます。
getInstance	関数	はい	getInstance	Captcha インスタンスをバインドする関数。固定の式は次のとおりです: `function getInstance(instance) { captcha = instance; }`
slideStyle	オブジェクト	いいえ	{ width: 360, height: 40 }	スライダー Captcha のスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。重要 Captcha は、ポリシーモデルが判断を下すためにスライドを通じて十分な情報を収集する必要があるため、スライダーの最小幅 (width 値) を 320 px に設定することをお勧めします。width 値が 320 px 未満の場合、システムはそれを 320 px として構成します。このパラメーターはスライダーモードでのみ有効であり、パズル Captcha には適用されません。パズル Captcha を使用している場合、パズル Captcha のイメージサイズと検証の答えは事前設定されているため、CSS を上書きしてスタイルを強制的に変更しないでください。そうしないと、検証例外が発生する可能性があります。
language	文字列	いいえ	cn	Captcha 2.0 でサポートされている言語タイプ。
immediate	ブール値	いいえ	false	埋め込みモードで、検証完了後すぐに検証リクエスト (captchaVerifyCallback 関数を呼び出す) を送信するかどうかを指定します。
timeout	数値	いいえ	5000	単一の Captcha 初期化リクエストのタイムアウト期間。単位: ミリ秒 (ms)。
rem	数値	いいえ	1	Captcha UI 全体をスケーリングします。正の数値を入力します。たとえば、0.5 はサイズを半分に縮小し、2 はサイズを 2 倍にすることを意味します。説明 rem パラメーターは主にモバイルブラウザで使用されます。
autoRefresh	ブール値	いいえ	true	検証が成功した後に Captcha を自動的にリフレッシュするかどうかを指定します。説明このパラメーターを false に設定した場合は、インスタンスメソッドを手動で呼び出して Captcha をリフレッシュする必要があります。詳細については、「よくある質問の Q4」をご参照ください。
onError	関数	いいえ	なし	失敗した、またはタイムアウトした Captcha 初期化 API リクエストのエラーコールバック関数。
captchaLogoImg	文字列	いいえ	なし	クリック検証ボタンの右側にある会社のロゴを置き換えるためのパラメーター。値は、イメージ URL または Base64 形式のデータにすることができます。

rem パラメーターのコード例

const customWidth = 360;
function initCaptcha(rem) {
  window.initAliyunCaptcha({
    SceneId: "xxxxxx",
    mode: "popup",
    element: "#captcha-element",
    button: "#captcha-button",
    success: success,
    fail: fail,
    getInstance: getInstance,
    slideStyle: {
      width: customWidth,
      height: 40,
    },
    language: "cn",
    rem: rem,
  });
}

const pageWidth = window.innerWidth;
if (pageWidth <= customWidth) {
  const rem = Math.floor(pageWidth / customWidth * 100) / 100;
  initCaptcha(rem);
}

captchaVerifyCallback パラメーター

リクエストパラメーター

パラメーター	タイプ	必須	デフォルト値	説明
captchaVerifyParam	文字列	はい	captchaVerifyParam	Captcha パラメーター。Captcha スクリプトによって返される検証パラメーター。このパラメーターを処理する必要はありません。サーバーに直接渡すことができます。

戻りパラメーター

パラメーター	タイプ	デフォルト値	説明
captchaResult	ブール値	なし	Captcha 検証が成功したかどうかを指定します。
bizResult	ブール値	なし	ビジネス検証が成功したかどうかを指定します。ビジネス検証結果がない場合、bizResult の値は空にすることができます。

:Web および H5 クライアント用の V2 アーキテクチャを統合する