V3 アーキテクチャを使用した Web および H5 クライアントとの統合 - Captcha

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

前提条件

Alibaba Cloud Captcha 2.0 サービスがアクティブ化されています。
認証シナリオが作成され、Integration Method が [Web/] [H5]に設定されています。

メソッドの概要

以下の 3 つのステップに従って、クライアントを Captcha 2.0 と統合します。

AliyunCaptchaConfig グローバル変数を追加します。
CAPTCHA JS ファイルを動的にロードします。
初期化メソッドを呼び出して Captcha を初期化します。

説明

ご利用のサービスが V2 アーキテクチャを使用している場合は、「V2 アーキテクチャを使用した Web および H5 クライアントとの統合」をご参照ください。
V3 アーキテクチャは WeChat ミニプログラムではサポートされていません。

操作手順

ステップ 1: AliyunCaptchaConfig グローバル変数を追加する

Alibaba Cloud CAPTCHA JS スクリプトをロードする前、または HTML の <head> タグの先頭に、AliyunCaptchaConfig という名前のグローバル変数を定義するスクリプトを追加します。この変数には、リージョンとプレフィックスのパラメーターを含める必要があります。

<script>
  window.AliyunCaptchaConfig = {
    // 必須。CAPTCHA インスタンスが存在するリージョン。有効な値：cn (中国本土) および sgp (シンガポール)。
    region: "cn",
    // 必須。ID プレフィックス。Captcha 2.0 をアクティブ化した後、コンソールの [概要] ページのインスタンス情報カードから ID プレフィックスを取得できます。
    prefix: "******",
  };
</script>

重要

ID プレフィックスは、次の図に示すように、Overview > Cumulative Activation Time > Identity Prefix で確認できます。

ステップ 2：CAPTCHA JS ファイルの動的なインポート

Web ページは CAPTCHA JS ファイルを動的にロードする必要があります。認証が必要な場合は、CAPTCHA サービスを呼び出して認証を実行します。

説明

CAPTCHA JS ファイルは動的にロードする必要があります。ローカルデプロイメントのために JS コードをダウンロードするなどして動的ロードをバイパスすると、CAPTCHA サービスを更新できません。これにより、セキュリティが損なわれ、誤ったブロックや互換性の問題が発生する可能性があります。

<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>

ステップ 3: 初期化メソッドを呼び出して Captcha を初期化する。

initAliyunCaptcha 初期化メソッドは、初期化パラメーターが変更された場合などの特定のシナリオを除き、繰り返し呼び出すべきではありません。初期化に失敗した場合は、「クライアント側の初期化エラー」をご参照ください。

<script type="text/javascript">
  var captcha;
  // region と prefix 以外のパラメーター
  window.initAliyunCaptcha({...});
</script>

コード例

説明

より完全な環境およびデバイス情報を収集するために、できるだけ早く CAPTCHA JS ファイルをロードしてください。JS ファイルのロードから認証リクエストの送信までの間隔は 2 秒より長くする必要があります。
イメージリソースの読み込みを高速化するために、できるだけ早く CAPTCHA を初期化してください。初期化から認証リクエストの送信までの間隔は 2 秒より長くする必要があります。これにより、CAPTCHA リソースがプリロードされ、イメージの読み込みが高速化されます。
クライアントのソースコードで、CAPTCHA サービス用のページ要素を予約します。`element` および `button` パラメーターは、次の例の <div id="captcha-element"></div> のように、この DOM 要素を指す必要があります。

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />
    <!--1. Alibaba Cloud CAPTCHA JS スクリプトをインポートする前、または HTML の head タグの先頭に、AliyunCaptchaConfig という名前のグローバル変数を保存するスクリプトを追加します。この変数には、リージョンとプレフィックスのパラメーターを含める必要があります。-->
    <script>
      window.AliyunCaptchaConfig = {
        // 必須。CAPTCHA インスタンスが存在するリージョン。有効な値：cn (中国本土) および sgp (シンガポール)。
        region: "cn",
        // 必須。ID プレフィックス。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>
    <div id="captcha-element"></div>
    <!--予約済みの CAPTCHA 要素。初期化関数で element パラメーターを設定するために使用されます。-->
    <button id="button" class="btn">Log on</button>
    <!--ポップアップモードでは、この要素が CAPTCHA ダイアログボックスをトリガーします。-->
    <!--3. <script> タグを作成して、initAliyunCaptcha 初期化関数を呼び出します。-->
    <script type="text/javascript">
      var captcha;
      // ポップアップモードでは、これらは region と prefix 以外のパラメーターです。
      window.initAliyunCaptcha({
        // シナリオ ID。認証シナリオを作成した後、認証シナリオのリストからその ID を取得できます。
        SceneId: "******",
        // CAPTCHA モード。`popup` はポップアップモードを示し、`embed` は埋め込みモードを示します。これを変更する必要はありません。
        mode: "popup",
        // CAPTCHA をレンダリングするためにページ上に予約された要素。これは、ソースコード内の予約済みページ要素と一致する必要があります。
        element: "#captcha-element",
        // CAPTCHA ダイアログボックスまたは無操作認証をトリガーする要素。
        button: "#button",
        // CAPTCHA 認証が成功した場合のコールバック関数。
        success: function (captchaVerifyParam) {
          // 入力パラメーターは、署名検証用の captchaVerifyParam です。
          // 1. バックエンドにリクエストを送信して captchaVerifyParam を検証します。
          // 2. 検証結果に基づいてサービスを処理します。
          // 3. サービスで再検証が必要な場合は、initAliyunCaptcha 初期化メソッドを呼び出して CAPTCHA を再初期化します。
        },
        // CAPTCHA 認証が失敗した場合のコールバック関数。
        fail: function (result) {
          // 入力パラメーターには失敗情報が含まれています。
          // 通常の有効期間内では、何もする必要はありません。CAPTCHA は再検証のために自動的にリフレッシュされます。
          console.error(result);
        },
        // CAPTCHA インスタンスをバインドするためのコールバック関数。このコールバックは、CAPTCHA が正常に初期化された後に呼び出されます。
        getInstance: function (instance) {
          captcha = instance;
        },
        // スライダー認証およびクリック認証のトリガーボックスのスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...その他のパラメーターについては、initAliyunCaptcha パラメーターの説明をご参照ください。
      });
    </script>
  </body>
</html>

パラメーターの説明

AliyunCaptchaConfig パラメーター

パラメーター

タイプ

必須

デフォルト値

説明

region

String

はい

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

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

重要

クライアントのリージョンが `cn` の場合は、サーバーで中国本土のエンドポイントを呼び出します。リージョンが `sgp` の場合は、シンガポールのエンドポイントを呼び出します。
このプロダクトは、中国本土 (中国 (上海)) とシンガポールにコントロールプレーンがあります。設定した呼び出しパラメーターに基づいて、クライアントは行動データとデバイスデータを収集し、対応するセンターに送信して処理します。これは主にセキュリティ認証に使用されます。

prefix

String

はい

なし

CAPTCHA の ID プレフィックス。Captcha 2.0 をアクティブ化した後、コンソールの [概要] ページ右上でこの値を取得できます。

initAliyunCaptcha パラメーター

ページが読み込まれた後、できるだけ早く Captcha 初期化メソッドを呼び出します。

パラメーター	タイプ	必須	デフォルト値	説明
SceneId	String	はい	なし	CAPTCHA のシナリオ ID。認証シナリオを作成した後にこの値を取得できます。
mode	String	はい	なし	Captcha モード。オプション: popup: ポップアップモード。 embed: 埋め込みモード。重要無操作認証は埋め込みモードをサポートしていません。統合にはポップアップモードを使用してください。
element	String	はい	なし	CAPTCHA をレンダリングするためにページ上に予約された要素。これは、ソースコード内の予約済みページ要素と一致する必要があります。
button	String	はい	なし	CAPTCHA ダイアログボックスまたは無操作認証をトリガーする要素。クリックすると、CAPTCHA が表示されるか、無操作認証がトリガーされます。値は、クライアント本文の `button` パラメーター値と同じである必要があります。
success	Function	はい	なし	CAPTCHA 認証が成功した場合のコールバック関数。この関数は認証パラメーターを渡します。このコールバック関数で、`CaptchaVerifyParam` を取得し、ご利用のサーバーにリクエストを送信して `CaptchaVerifyParam` を検証できます。
fail	Function	いいえ	なし	Captcha 検証が失敗した場合のコールバック関数。この関数は、失敗のエラーコードを公開します。
getInstance	Function	はい	getInstance	CAPTCHA インスタンスをバインドするためのコールバック関数。このコールバックは、CAPTCHA が正常に初期化された後に呼び出されます。構文は固定です： `function getInstance(instance) { captcha = instance; }`
slideStyle	Object	いいえ	{ width: 360, height: 40 }	スライダー認証およびクリック認証のトリガーボックスのスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。このパラメーターは、過去のパラメーター名と互換性があります。重要 CAPTCHA は、ポリシーモデルが判断を下すためにスライド操作から十分な情報を収集する必要があるため、最小スライダー幅 (width 値) を 320 px に設定してください。width 値が 320 px 未満の場合、システムは 320 px を使用します。このパラメーターは、パズル認証や画像修復認証には適用されません。パズル CAPTCHA を使用する場合は、CSS をオーバーライドしてスタイルを強制的に変更しないでください。パズル CAPTCHA のイメージサイズと認証の答えは事前に設定されており、固定されています。スタイルを変更すると、認証が失敗します。
language	String	いいえ	cn	Captcha 2.0 でサポートされている言語タイプ。
timeout	Number	いいえ	5000	単一の Captcha 初期化リクエストのタイムアウト期間 (ミリ秒 (ms))。
rem	Number	いいえ	1	Captcha UI 全体をスケーリングします。正の数値を入力します。たとえば、0.5 はサイズを半分にし、2 はサイズを 2 倍にします。説明 rem パラメーターは主にモバイルブラウザ用です。
onError	Function	いいえ	なし	CAPTCHA 初期化 API リクエストおよびリソース読み込みの失敗またはタイムアウトに対するエラーコールバック関数。
onClose	Function	いいえ	なし	CAPTCHA ダイアログボックスが閉じられたときにトリガーされるコールバック関数。
captchaLogoImg	String	いいえ	なし	埋め込みモードでのクリック認証、パズル認証、または画像修復認証のトリガーボタンの右側にある会社のロゴを置き換えるパラメーター。値は、イメージ URL または Base64 エンコードされたデータにすることができます。
dualStack	Boolean	いいえ	false	初期化リクエストドメイン名と検証リクエストドメイン名に対してデュアルスタックを有効にするかどうかを指定します。有効な値: false: IPv4 のみがサポートされます。 true: IPv4 と IPv6 の両方がサポートされます。
UserCertifyId	String	いいえ	なし	生成するカスタムの `certifyId`。このパラメーターはオプションです。パススルーパラメーターを使用してサービスフローを関連付けたいシナリオで使用されます。サーバー側の署名検証 API は、お客様の検証をサポートするためにこのパラメーターを返します。重要パラメーターのフォーマット：ID プレフィックス (prefix)_10 桁のランダムな文字列 (大文字、小文字、数字を含む)。例：`1q5***_7G47iByes3`。コード例については、「UserCertifyId パラメーターのコード例」をご参照ください。
showErrorTip	Boolean	いいえ	true	ネットワーク品質が低い場合に、アクセス例外のエラーメッセージを表示するかどうかを指定します。
delayBeforeSuccess	Boolean	いいえ	true	認証成功後、success コールバック関数を 1 秒遅延させるかどうかを指定します。デフォルト値は true です。

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);
}

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

// コード例
function generateRandomString(length) {
  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  let result = '';
  const charactersLength = characters.length;
  for (let i = 0; i < length; i++) {
    result += characters.charAt(Math.floor(Math.random() * charactersLength));
  }
  return result;
}

const initCaptcha = async () => {
  const prefix = 'xxxxxx';
  const UserCertifyId = prefix + '_' + generateRandomString(10);

  // Alibaba Cloud CAPTCHA の初期化ロジック
  window.initAliyunCaptcha({
    // 必要なフォーマットでカスタム certifyId を生成し、初期化メソッドに渡します。
    UserCertifyId: UserCertifyId,
    // ...その他のパラメーターについては、initAliyunCaptcha パラメーターの説明をご参照ください。
  });
};

メソッド呼び出しの説明

CAPTCHA インスタンスの対応するメソッドを呼び出すことができます。以下のメソッドは、無操作認証モードでの最初の認証ではサポートされていません。

メソッド名

説明

例

シナリオ

show

CAPTCHA 要素とマスクを表示します。

captcha.show()

ボタンをクリックせずに CAPTCHA ダイアログボックスを自動的にポップアップさせる必要がある場合に使用します。

hide

Captcha 要素とマスクを非表示にするか閉じます。

captcha.hide()

ボタンをクリックせずに CAPTCHA ダイアログボックスを自動的に閉じる必要がある場合に使用します。

返されるデータ

V3 クライアントアーキテクチャを使用して Captcha 2.0 と統合して動作検証を行うと、CAPTCHA サーバーはユーザーの動作を検証して、リクエストがマシンからのものかどうかを判断します。その後、サーバーは CAPTCHA コードとその他のパラメーターをクライアントに返します。ブラウザのネットワーク機能を使用して、返されたデータを表示できます。詳細については、「V3 クライアントアーキテクチャによって返されるデータ」をご参照ください。

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

Captcha:V3 アーキテクチャを使用した Web および H5 クライアントとの統合