Web および H5 クライアントの V2 統合 - - Alibaba Cloud ドキュメントセンター

コンソールで認証シナリオを追加した後、認証が必要な Web または H5 ページにキャプチャの初期化コードを統合します。このトピックでは、このクライアント側の統合について説明します。

前提条件

開始する前に、以下をご確認ください。

Alibaba Cloud キャプチャ 2.0 を有効化済みであること
認証シナリオを作成し、統合方法を Web/H5 に設定済みであること

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

Slider CAPTCHA、Puzzle Verification、One-click CAPTCHA、およびImage Restoration

シーケンス図の説明：

お客様がビジネスクライアントでキャプチャを初期化します。ビジネスクライアントはキャプチャサーバーにリクエストを送信し、イメージやチャレンジなどのキャプチャリソースを取得します。

リクエストが失敗した場合、返されたエラーメッセージを基に原因を特定し、問題を解決できます。
ユーザーが Web ページでキャプチャインタラクション (スライダー CAPTCHA、パズル認証、ワンクリック認証、画像修復など) とビジネスインタラクション (ログインや登録など) を完了します。

インタラクションが完了すると、ビジネスクライアントはキャプチャパラメーターとビジネスパラメーターをビジネスサーバーに送信します。
ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために認証リクエストをキャプチャサーバーに送信します。
キャプチャサーバーは認証リスクを評価し、認証結果をビジネスサーバーに返します。
ビジネスサーバーはリクエストを処理し、認証とビジネスの結果をビジネスクライアントに返します。
クライアントページでメッセージを表示し、ビジネス操作を処理します。

認証が失敗した場合、キャプチャはリフレッシュされ、プロセスはステップ 1 に戻ります。

Invisible CAPTCHA

シーケンス図の説明：

お客様がビジネスクライアントでキャプチャを初期化します。ビジネスクライアントはキャプチャサーバーにリクエストを送信し、イメージやチャレンジなどのキャプチャリソースを取得します。

リクエストが失敗した場合、返されたエラーメッセージを基に原因を特定し、問題を解決できます。
ユーザーがビジネスクライアントでビジネスインタラクション (ログインや登録など) を完了します。

インタラクションが完了すると、ビジネスクライアントは不可視 CAPTCHA パラメーターとビジネスパラメーターをビジネスサーバーに送信します。
ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために認証リクエストをキャプチャサーバーに送信します。
キャプチャサーバーは認証リスクを評価し、認証結果をビジネスサーバーに返します。
ビジネスサーバーはリクエストを処理します。
- ユーザーがリスキーと見なされない場合、認証プロセスは終了します。
- ユーザーがリスキーと見なされる場合、二次認証がトリガーされます。
  1. ユーザーが Web ページでキャプチャインタラクション (スライダー CAPTCHA、パズル認証、ワンクリック認証、画像修復など) とビジネスインタラクション (ログインや登録など) を完了します。
    
    インタラクションが完了すると、ビジネスクライアントはキャプチャパラメーターとビジネスパラメーターをビジネスサーバーに送信します。
  2. ビジネスサーバーは VerifyIntelligentCaptcha API を呼び出し、脅威分析のために認証リクエストをキャプチャサーバーに送信します。
  3. キャプチャサーバーは認証リスクを評価し、認証結果をビジネスサーバーに返します。
  4. ビジネスサーバーはリクエストを処理し、認証とビジネスの結果をビジネスクライアントに返します。
  5. クライアントページでメッセージを表示し、ビジネス操作を処理します。
    
    認証が失敗した場合、キャプチャはリフレッシュされ、プロセスは二次認証の開始に戻ります。

キャプチャ初期化コードの統合

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

クライアントのソースコードで、キャプチャをレンダリングするためのページ要素を確保します。element および button パラメーターは、この DOM 要素を参照します (例：以下のサンプルコードの <div id="captcha-element"></div>)。キャプチャタイプを切り替えた際にキャプチャの高さが変更されても、キャプチャ要素がコンテナの高さを超えないように、ビジネスモジュールのコンテナの高さをアダプティブに設定することを推奨します。

重要

統合後、コンソールでキャプチャモードなどのシナリオ構成を変更した場合でも、初期化パラメーターやページ構造を調整する必要はありません。キャプチャは新しい構成をオンデマンドでロードします。

// 元のクライアントコードの例
 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/';
   }
 }
// クライアントの body 内のコード
<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>  // キャプチャ用の予約済みページ要素。初期化関数で element パラメーターを設定するために使用します。
            <button id="button" class="login-btn">Log on</button>
        </div>
    </div>
</div>

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

重要

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

ポップアップ

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

埋め込み

<!doctype html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="data-spm" />
        <!-- 1. Alibaba Cloud キャプチャ JS スクリプトをインポートする前、または HTML ファイルの <head> タグの先頭に、region および prefix パラメーターを含む AliyunCaptchaConfig という名前のグローバル変数を保存するスクリプトを追加します。
        -->
        <script>
            window.AliyunCaptchaConfig = {
                // 必須。キャプチャインスタンスが存在するリージョン。有効な値：cn (中国本土) および sgp (シンガポール)。
                region: "cn",
                // 必須。ID 認証情報。Alibaba Cloud キャプチャ 2.0 を有効化した後、コンソールの [概要] ページの [インスタンス基本情報] カードから取得します。
                prefix: "xxxxxx",
            };
        </script>
        <!-- 2. メインの JS を統合します。 -->
        <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js">
        </script>
    </head>
    <body>
        <!-- 3. <script> タグを作成して、キャプチャ初期化関数 initAliyunCaptcha を呼び出します。 -->
        <script type="text/javascript">
            var captcha;
            // 埋め込みモードのパラメーター (region と prefix を除く)。
            window.initAliyunCaptcha({
                // シナリオ ID。認証シナリオを作成した後、コンソールの認証シナリオリストからその ID を取得できます。
                SceneId: 'c9h3****',
                // キャプチャモード。「embed」は埋め込みモードを示します。このパラメーターは変更しないでください。
                mode: 'embed',
                // キャプチャがレンダリングされる DOM 要素。予約した要素と一致させる必要があります。
                element: '#captcha-element',
                // ビジネスリクエストをトリガーする要素。「#button」は、ログインボタンがクリックされたときに captchaVerifyCallback 関数がトリガーされることを示します。ご利用の要素に合わせて「button」の値を変更してください。
                button: '#button',
                // キャプチャ認証付きのビジネスリクエスト用のコールバック関数。変更しないでください。
                captchaVerifyCallback: captchaVerifyCallback,
                // ビジネスリクエスト結果用のコールバック関数。変更しないでください。
                onBizResultCallback: onBizResultCallback,
                // キャプチャインスタンスをバインドする関数。変更しないでください。
                getInstance: getInstance,
                // スライダー CAPTCHA のスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。最小幅は 320 px です。
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // キャプチャの言語。有効な値：cn (簡体字中国語)、tw (繁体字中国語)、en (英語)。
                language: 'cn',
                // ユーザーがチャレンジに成功した後、すぐに認証リクエスト (captchaVerifyCallback を呼び出す) を送信するかどうかを指定します。
                immediate: false,
            });
            // キャプチャインスタンスをバインドします。これは標準関数であり、変更する必要はありません。
            function getInstance(instance) {
                captcha = instance;
            }
            // キャプチャ認証付きのビジネスリクエスト用のコールバック関数。
            /**
              * @name captchaVerifyCallback
              * @function
              * @param {string} captchaVerifyParam - キャプチャスクリプトによって返される認証パラメーター。このパラメーターを処理せずにサーバーに直接渡します。
              * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}} - 戻りオブジェクト。フィールド名は固定です。captchaResult は必須です。bizResult はオプションで、ビジネス認証シナリオがない場合は省略できます。
              */
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1. ビジネスリクエストをバックエンドに送信して、キャプチャとビジネスの認証結果を取得します。
                const result = await xxxx('http://Your business request address', {
                    // キャプチャパラメーター
                    captchaVerifyParam: captchaVerifyParam,
                    // ビジネスパラメーター
                    yourBizParam... 
                });
                // 2. 標準の戻りオブジェクトを構築します。
                const verifyResult = {
                    // captchaResult: 必須。キャプチャ認証が成功したかどうかを示すブール値。
                    captchaResult: result.captchaVerifyResult,
                    // bizResult: オプション。ビジネス認証が成功したかどうかを示すブール値。該当しない場合は省略します。
                    bizResult: getYourBusinessResult(result),
                };
                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>

ES5 構文については、次の例をご参照ください。この例では、コールバック関数を captchaVerifyCallback の 2 番目のパラメーターとして使用して、認証結果を受け取ります。

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

統合中にご不明な点がある場合は、チケットを起票してください。

パラメーター

AliyunCaptchaConfig パラメーター

パラメーター

タイプ

必須

デフォルト

説明

region

String

はい

キャプチャインスタンスのリージョン。有効な値：

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

重要

クライアント側の region パラメーターがサーバー側のエンドポイントアドレスと一致しない場合、認証リクエストは失敗します。
キャプチャ 2.0 は、中国本土 (中国 (上海)) とシンガポールにコントロールプレーンがあります。設定した呼び出しパラメーターに応じて、クライアントは対応するセンターに動作およびデバイスデータを送信し、セキュリティ検証を行います。

prefix

String

はい

なし

キャプチャ 2.0 の ID 認証情報。取得するには、キャプチャ 2.0 を有効化し、キャプチャ 2.0 コンソールにログインして、[概要] ページの下部にある ID 認証情報 を見つけます。この ID はパラメーター設定に使用されます。

initAliyunCaptcha パラメーター

パラメーター	タイプ	必須	デフォルト	説明
SceneId	String	はい	なし	キャプチャのシナリオ ID。認証シナリオを作成した後、キャプチャ 2.0 コンソールにログインし、[シナリオ管理] ページに移動して、[シナリオ名/ID] 列でシナリオの `SceneId` 値を見つけます。
mode	String	はい	なし	キャプチャモード。有効な値： popup：ポップアップモード。 embed：埋め込みモード。重要無操作認証は埋め込みモードをサポートしていません。統合にはポップアップモードを使用してください。
element	String	はい	captcha-element	キャプチャがレンダリングされるページ要素。ソースコード内の対応する要素と一致させる必要があります。
button	String	はい	なし	クリックされたときにキャプチャのポップアップをトリガーする要素のセレクター。
captchaVerifyCallback	Function	はい	captchaVerifyCallback	キャプチャ認証が成功した後にビジネスロジックを処理するためのコールバック関数。詳細については、「captchaVerifyCallback」をご参照ください。
onBizResultCallback	Function	はい	onBizResultCallback	ビジネスリクエスト結果のコールバック関数。この関数を使用して、認証結果を処理するロジックを定義します。
getInstance	Function	はい	getInstance	キャプチャインスタンスを受け取るコールバック。構文は次のように固定されています。 `function getInstance(instance) { captcha = instance; }`
slideStyle	Object	いいえ	{ width: 360, height: 40 }	スライダー CAPTCHA のスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。重要効果的な認証を確保するために、スライダーの最小 `width` を 320 px に設定してください。指定された `width` が 320 px 未満の場合、システムはデフォルトで 320 px になります。このパラメーターはスライダー CAPTCHA にのみ適用されます。パズル CAPTCHA のスタイルをこのパラメーターや CSS の上書きで変更しようとしないでください。プリセットされたディメンションは認証にとって重要です。スタイルを変更すると失敗の原因となります。
language	String	いいえ	cn	キャプチャ UI の表示言語を指定します。サポートされている言語については、「言語タイプ」をご参照ください。
immediate	Boolean	いいえ	false	埋め込みモードで、ユーザーが認証に成功した直後に captchaVerifyCallback 関数を呼び出すかどうかを指定します。
timeout	Number	いいえ	5000	単一のキャプチャ初期化リクエストのタイムアウト期間 (ミリ秒単位)。
rem	Number	いいえ	1	キャプチャ UI 全体をスケーリングします。正の数値を入力します。たとえば、`0.5` はサイズを半分に縮小し、`2` はサイズを 2 倍にします。説明 rem パラメーターは主にモバイルブラウザで使用されます。
autoRefresh	Boolean	いいえ	true	ユーザーが認証に成功した後にキャプチャを自動的にリフレッシュするかどうかを指定します。説明このパラメーターを `false` に設定した場合、インスタンスメソッドを手動で呼び出してキャプチャをリフレッシュする必要があります。詳細については、「よくある質問の Q4」をご参照ください。
onError	Function	いいえ	なし	失敗またはタイムアウトしたキャプチャ初期化 API リクエストのエラーコールバック関数。
captchaLogoImg	String	いいえ	なし	クリック認証ボタンの右側にあるデフォルトのロゴを置き換えます。値はイメージ 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	String	はい	captchaVerifyParam	キャプチャスクリプトによって返される認証パラメーター。このパラメーターを変更せずにサーバーに直接渡します。

戻りパラメーター

パラメーター	タイプ	デフォルト	説明
captchaResult	Boolean	なし	キャプチャ認証が成功したかどうかを示します。
bizResult	Boolean	なし	ビジネス認証が成功したかどうかを示します。ビジネス認証結果がない場合は、この値を省略できます。

:Web および H5 クライアントの V2 統合

前提条件

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

Slider CAPTCHA、Puzzle Verification、One-click CAPTCHA、およびImage Restoration

Invisible CAPTCHA

キャプチャ初期化コードの統合

ポップアップ

埋め込み

パラメーター

AliyunCaptchaConfig パラメーター

initAliyunCaptcha パラメーター

`captchaVerifyCallback` パラメーター

クライアント V2 アーキテクチャのデモ

前提条件

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

Slider CAPTCHA、Puzzle Verification、One-click CAPTCHA、およびImage Restoration

Invisible CAPTCHA

キャプチャ初期化コードの統合

ポップアップ

埋め込み

パラメーター

AliyunCaptchaConfig パラメーター

initAliyunCaptcha パラメーター

captchaVerifyCallback パラメーター

クライアント V2 アーキテクチャのデモ

`captchaVerifyCallback` パラメーター