すべてのプロダクト
Search

このプロダクト

    Captcha:Web および H5 クライアント統合 (V3 アーキテクチャ)

    ドキュメントセンター

    Captcha:Web および H5 クライアント統合 (V3 アーキテクチャ)

    最終更新日:Jul 14, 2026

    コンソールで検証シナリオを追加した後、Captcha 初期化コードを Web または H5 ページに統合します。このトピックでは、統合プロセスについて説明します。

    前提条件

    方法の概要

    わずか 3 ステップで、ビジネス クライアントを Captcha 2.0 と連携できます：

    1. グローバル変数 AliyunCaptchaConfig を追加します。

    2. Captcha JS スクリプトを動的に読み込みます。

    3. 初期化メソッドを呼び出します。

    説明

    操作手順

    ステップ 1： AliyunCaptchaConfig グローバル変数の追加

    Alibaba Cloud CAPTCHA JS スクリプトを読み込む前、または HTML の head タグの先頭に、AliyunCaptchaConfig という名前のグローバル変数を定義するスクリプトを追加します。この変数には、region および prefix パラメータを含めます。

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

    プレフィックスは、以下の図に示すように、概要 > 累計利用期間 > ユーザー種別 セクションで確認できます。

    image

    ステップ 2： Captcha JS の動的読み込み

    Captcha JS スクリプトを Web ページに動的に読み込みます。これにより、必要に応じて Captcha を呼び出して検証を実行できます。

    説明

    Captcha JS スクリプトは動的に読み込む必要があります。たとえば、JS をダウンロードしてローカルにデプロイするなど、動的読み込みをバイパスすると、サービスが正しく更新されなくなります。これにより、セキュリティの脆弱性、誤ったブロック、または互換性の問題が発生する可能性があります。スクリプトを複数回読み込まないでください。検証が失敗する可能性があります。

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

    ステップ 3： 初期化メソッドの呼び出し

    初期化中に initAliyunCaptcha メソッドが失敗した場合は、「クライアント初期化エラー」をご参照ください。

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

    コード例

    説明

    • Captcha JS スクリプトをできるだけ早く読み込み、より完全な環境およびデバイス情報を収集できるようにしてください。スクリプトの読み込みと検証リクエストの開始の間に、少なくとも 2 秒の間隔を空けてください。

    • 画像リソースの読み込みを高速化するために、Captcha をできるだけ早く初期化してください。これにより、関連リソースが事前に読み込まれ、画像の読み込みが高速化されます。初期化と検証リクエストの間に少なくとも 2 秒の間隔を空けてください。

    • クライアントのソースコードで、Captcha 用のプレースホルダー要素を作成してください。この DOM 要素は、次の例の element および button パラメータ (<div id="captcha-element"></div> など) によって参照されます。

    <!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",
        // 必須。Captcha インスタンスのプレフィックス。Alibaba Cloud Captcha 2.0 を有効化した後、コンソールの [概要] ページの [インスタンス情報] カードからプレフィックスを取得できます。
        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">ログオン</button>
    <!-- ポップアップモードでは、この要素が Captcha ダイアログをトリガーします。 -->
    <!-- 3. <script> タグを作成して、Captcha 初期化関数 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",
        // 検証成功時のコールバック関数。
        success: function (captchaVerifyParam) {
          // 入力パラメータは captchaVerifyParam です。
          // 1. バックエンドにリクエストを送信して、captchaVerifyParam を検証します。
          // 2. 検証結果に基づいてビジネスロジックを処理します。
          // 3. ビジネスで再検証が必要な場合は、initAliyunCaptcha メソッドを呼び出して 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

    はい

    cn

    Captcha インスタンスが配置されているリージョン。有効な値：

    • cn：中国本土。

    • sgp：シンガポール。

    重要

    • クライアントリージョンが cn の場合、サーバー側は中国本土のエンドポイントを呼び出してください。リージョンが sgp の場合は、シンガポールのエンドポイントを呼び出してください。

    • サービスには、中国 (上海) およびシンガポールリージョンにコントロールプレーンセンターがあります。指定した region パラメータに基づいて、行動情報やデバイス情報などのクライアント側データが対応するセンターに送信され、セキュリティ検証が実行されます。

    prefix

    String

    はい

    なし

    Captcha インスタンスのプレフィックス。Alibaba Cloud Captcha 2.0 を有効化した後、コンソールの [概要] ページの右上隅でこのプレフィックスを確認できます。image

    initAliyunCaptcha パラメータ

    ページの読み込み後、できるだけ早く Captcha 初期化メソッドを呼び出してください。

    パラメータ

    型

    必須

    デフォルト

    説明

    SceneId

    String

    はい

    なし

    Captcha のシーン ID。検証シナリオを作成すると、この値を取得できます。image

    mode

    String

    はい

    なし

    Captcha モード。有効な値：

    • popup：Captcha がダイアログボックスに表示されます。

    • embed：Captcha がページに埋め込まれます。

      重要

      トレースレス検証は埋め込みモードをサポートしていません。代わりにポップアップモードを使用してください。

    element

    String

    はい

    なし

    Captcha がレンダリングされる HTML 要素のセレクタ。値は、'#captcha-element' などの有効な CSS セレクタである必要があります。

    button

    String

    はい

    なし

    Captcha をトリガーする HTML 要素のセレクタ。この要素をクリックすると、Captcha ダイアログが表示されるか、トレースレス検証が開始されます。値は、'#my-button' などの有効な CSS セレクタである必要があります。

    success

    Function

    はい

    なし

    CAPTCHA 検証が成功した場合のコールバック関数です。引数として検証パラメータが渡されます。このコールバック関数内で、CaptchaVerifyParam を取得し、サーバーにリクエストして CaptchaVerifyParam の検証を実行できます。

    fail

    Function

    いいえ

    なし

    検証が失敗した場合に実行されるコールバック関数。失敗に関する詳細を含むオブジェクトを受け取ります。

    getInstance

    Function

    はい

    なし

    Captcha が正常に初期化された後にインスタンスオブジェクトを取得するためのコールバック関数です。この関数を使用してインスタンスへの参照を取得します。

    function getInstance(instance) {
  captcha = instance;
}

    slideStyle

    Object

    いいえ

    { width: 360, height: 40 }

    スライダーおよびクリック検証チャレンジのトリガーボックスのスタイル。幅と高さをピクセル (px) 単位でカスタマイズできます。このパラメータは、従来のパラメータ名と互換性があります。

    重要

    • 正確な検証を確実に行うために、システムはスライドアクションから十分なデータを収集する必要があります。スライダーの width は少なくとも 320 px を推奨します。width が 320 px 未満の場合、システムは 320 px として設定します。

    • このパラメータは、ジグソーパズルおよび画像復元チャレンジには適用されません。ジグソーパズル Captcha を使用している場合は、CSS を上書きしてスタイルを強制的に変更しないでください。ジグソーパズル Captcha の画像サイズと検証の正解は固定されており、スタイルを変更すると検証が失敗します。

    language

    String

    いいえ

    cn

    Alibaba Cloud Captcha 2.0 でサポートされている言語。

    timeout

    Number

    いいえ

    5000

    単一の Captcha 初期化リクエストのタイムアウト時間 (ミリ秒単位 (ms))。

    rem

    Number

    いいえ

    1

    Captcha UI 全体をスケーリングします。値は乗数として機能します。たとえば、0.5 はサイズを半分にし、2 は 2 倍にします。正の数である必要があります。

    説明

    rem パラメーターは、主にモバイルブラウザを対象としています。

    onError

    Function

    いいえ

    なし

    Captcha 初期化 API リクエストおよびリソース読み込みの失敗またはタイムアウト時のエラーコールバック関数。次の固定形式を使用します。

    function onError(errorInfo) { 
  const {code, msg} = errorInfo;
  console.log(code, msg);
}

    onClose

    Function

    いいえ

    なし

    検証コードポップアップが閉じられると、onClose コールバックがトリガーされます。パラメータ reason は、閉じられた具体的な理由を示します。指定できる値は次のとおりです：

    • userDismiss：ユーザーが手動でダイアログを閉じました。

    • verifyComplete：検証プロセスが完了し、SDK が自動的にダイアログを閉じます。これには、検証成功後の自動クローズおよびディザスタリカバリシナリオが含まれます。

    次の固定形式を使用します。

    function onClose(reason: string) {
  console.log('captcha closed:', reason);
}

    captchaLogoImg

    String

    いいえ

    なし

    埋め込みクリック検証、ジグソーパズル、または画像復元チャレンジのトリガーボタンの右側に表示される会社ロゴを置き換えるためのパラメータ。値は、画像 URL または Base64 エンコードされた文字列にすることができます。

    dualStack

    Boolean

    いいえ

    false

    初期化および検証リクエストドメイン名のデュアルスタックサポートを有効にするかどうかを指定します。有効な値：

    • false：IPv4 のみをサポートします。

    • true：IPv4 と IPv6 の両方をサポートします。

    UserCertifyId

    String

    いいえ

    なし

    ユーザーが生成するカスタムの certifyId です。このオプションパラメータは、サーバー側の検証 API に渡されてそのまま返されるため、バックエンドで検証できます。

    重要

    形式：プレフィックス_ 10 文字のランダム文字列。ランダム文字列には、大文字、小文字、および数字を使用できます。例：1q5***_7G47iByes3。コード例については、「UserCertifyId パラメータのコード例」をご参照ください。

    showErrorTip

    Boolean

    いいえ

    true

    ネットワーク品質の低下によるアクセス異常のエラーメッセージを表示するかどうかを指定します。

    delayBeforeSuccess

    Boolean

    いいえ

    true

    検証成功後、success コールバック関数のトリガーを 1 秒遅延させるかどうかを指定します。デフォルト値は true です。

    EncryptedSceneId

    String

    いいえ

    なし

    暗号化された SceneId です。検証シナリオを作成すると、元の SceneId を受け取ります。コンソールから発行された キー (ekey) を使用して、ドキュメントに記載されている暗号化プロセスに従って SceneId を暗号化します。結果として得られる暗号化された文字列が、このパラメーターの値です。

    zIndex

    Number

    いいえ

    なし

    Captcha 要素ブロックのレイヤーレベル (z-index)。現在のデフォルトは 1000000 です。このパラメータを使用して変更できます。

    disableMaskClick

    Boolean

    いいえ

    false

    マスクレイヤー (ダイアログの外側の領域) をクリックして Captcha を閉じるかどうかを指定します。true の場合、マスクをクリックしても何も起こりません。false (デフォルト) の場合、マスクをクリックするとダイアログが閉じます。

    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 ダイアログを閉じます。

    説明

    トレースレス検証モードではサポートされていません。

    startTracelessVerification

    トレースレス検証メソッドを単独で呼び出します。

    captcha.startTracelessVerification()

    このメソッドは、トレースレス検証モード専用です。ユーザーがトリガー要素をクリックするのを待つのではなく、たとえばビジネスロジックチェックを実行した後に、プログラムで検証を開始できます。

    トレースレス検証の単独呼び出しのコード例

    <!doctype html>
<link rel="shortcut icon" href="//www.aliyun.com/favicon.ico" type="image/x-icon" />
<script>
  window.AliyunCaptchaConfig = {
    region: 'cn',
    prefix: 'prefix',
  };
</script>
<script type="text/javascript" src="AliyunCaptcha.js"></script>

<div>
  <button id="login-button" class="login-btn">ログオン</button>
</div>

<script type="text/javascript">
  var captcha;

  function initCaptcha() {
      window.initAliyunCaptcha({
        // showErrorTip: false,
        delayBeforeSuccess: false,
        SceneId: 'SceneId',
        mode: 'popup',
        element: '#traceless-element',
        success: function(){
          
        },
        getInstance: function(instance){
          captcha = instance;
        },
        slideStyle: {
          width: 360,
          height: 40,
        },
        language: 'cn',
      });  
    }
  }

  initCaptcha();

  document.getElementById('login-button').onclick = function() {
    // ここにビジネスロジックを記述します
    ...
    
    // ダイアログを表示します。
    captcha.show();
    // トレースレス検証を開始します。
    captcha.startTracelessVerification();

    // ここにビジネスロジックを記述します
    ...
  }


</script>

    返されたデータ

    Alibaba Cloud Captcha 2.0 V3 クライアントアーキテクチャを統合すると、Alibaba Cloud Captcha 2.0 サーバーはユーザーの応答を検証し、リクエストが人間によるものかを判断します。その後、サーバーは検証データをクライアントに返します。返されたデータは、ブラウザの [ネットワーク] タブで表示できます。詳細については、「V3 クライアントアーキテクチャによって返されるデータ」をご参照ください。

    lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

    V3 クライアントアーキテクチャのデモダウンロード