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

Captcha 2.0 は、正しい順序で設定する必要がある 2 つの構成エントリを使用します。ページの読み込み前に、グローバル変数 AliyunCaptchaConfig を定義してインスタンスを識別します。ページの読み込み後、initAliyunCaptcha を呼び出して CAPTCHA ウィジェットをレンダリングし、認証結果を処理します。このトピックでは、これら両方のステップを完了する方法について説明します。

説明

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

前提条件

開始する前に、以下が完了していることを確認してください。

Alibaba Cloud Captcha 2.0 のアクティベーション
「検証シナリオ」を作成し、統合方法を[Web/H5]に設定しました。

仕組み

統合は、常に以下の 3 つのステップの順序で行います。

Captcha JS ファイルが読み込まれる前に、HTML の <head> 内で AliyunCaptchaConfig を定義します。
Alibaba Cloud の CDN から Captcha JS ファイルを動的に読み込みます。
initAliyunCaptcha を呼び出して CAPTCHA ウィジェットをレンダリングし、コールバックを登録します。

認証のライフサイクル全体は以下の通りです。

ページの読み込み： Captcha JS ファイルが読み込まれ、環境およびデバイスデータの収集を開始します。
ウィジェットのレンダリング： initAliyunCaptcha がウィジェットをレンダリングし、イメージリソースをプリロードします。
ユーザーインタラクション：ユーザーがウィジェットをトリガーします。Captcha 2.0 が動作およびデバイスの信号を分析します。
トークンの生成：成功すると、Captcha 2.0 は captchaVerifyParam を success コールバックに返します。
サーバー検証：ご利用のバックエンドが captchaVerifyParam を Captcha 2.0 のサーバーサイド API に送信して検証します。検証結果に基づいてビジネスロジックで処理を実行します。

重要

Captcha JS ファイルの読み込みから認証リクエストの送信までの間隔は 2 秒以上である必要があります。初期化から認証リクエストの送信までの間隔も 2 秒以上である必要があります。Captcha が環境データを収集し、イメージリソースをプリロードするのに十分な時間を与えるために、JS ファイルを読み込み、initAliyunCaptcha をできるだけ早く呼び出してください。

モードの選択

initAliyunCaptcha は 2 つのレンダリングモードをサポートしています。統合を開始する前に、いずれかを選択してください。

	ポップアップモード	埋め込みモード
トリガー	ボタンのクリックで CAPTCHA ダイアログボックスが開く	ウィジェットが常にページに表示される
必要な DOM 要素	はい — コンテナ要素とボタン要素	はい — コンテナ要素
No-captcha (操作不要認証) サポート	はい	いいえ — No-captcha 認証にはポップアップモードが必要です
推奨されるユースケース	ログインや登録フォームを含む、ほとんどのユースケース	CAPTCHA ウィジェットが永続的な UI 要素であるページ

Captcha 2.0 の統合

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

HTML の <head> 内で、Captcha JS ファイルへの参照の前に、window.AliyunCaptchaConfig を定義する <script> ブロックを追加します。

<script>
  window.AliyunCaptchaConfig = {
    // 必須。有効な値：cn (中国本土)、sgp (シンガポール)。
    region: "cn",
    // 必須。コンソールの [概要] > [累計アクティベーション時間] > [ID プレフィックス] からこの値を取得します。
    prefix: "xxxxxx",
  };
</script>

重要

ID プレフィックスは、コンソールの [概要] > 累計アクティベーション時間 > ID プレフィックス から取得します。以下に示します：

region の値は、Captcha 2.0 が動作およびデバイスデータを処理するために使用するコントロールプレーンを制御します。サーバーサイドのエンドポイントは一致している必要があります。region が cn の場合は中国本土のエンドポイントを使用し、region が sgp の場合はシンガポールのエンドポイントを使用します。エンドポイントの詳細については、「サーバーサイドアクセス」をご参照ください。

ステップ 2： Captcha JS ファイルの動的な読み込み

以下の <script> タグを追加して、Alibaba Cloud の CDN から Captcha JS ファイルを読み込みます。

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

重要

Captcha JS ファイルは、常に CDN から動的に読み込んでください。ファイルをダウンロードしてローカルでホストすると、Captcha サービスが更新を受け取れなくなり、セキュリティが損なわれたり、ブロッキングや互換性の問題が発生したりする可能性があります。

ステップ 3： Captcha の初期化

ページの読み込み後、initAliyunCaptcha を一度呼び出してウィジェットをレンダリングし、認証コールバックをバインドします。

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

説明

initAliyunCaptcha は、ページの読み込みごとに一度だけ呼び出してください。再初期化は、初期化パラメーターが変更された場合など、特定のシナリオでのみ行ってください。初期化に失敗した場合は、トラブルシューティングのために「クライアントサイドの初期化エラー」をご参照ください。

コード例

以下の完全な例は、ポップアップモードの統合を示しています。このページでは、CAPTCHA ウィジェットコンテナ用とトリガーボタン用の 2 つの DOM 要素を予約しています。

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />

    <!-- ステップ 1： Captcha JS ファイルが読み込まれる前に AliyunCaptchaConfig を定義します。 -->
    <script>
      window.AliyunCaptchaConfig = {
        // 有効な値：cn (中国本土)、sgp (シンガポール)。
        region: "cn",
        // [概要] > [累計アクティベーション時間] > [ID プレフィックス] から取得します。
        prefix: "xxxxxx",
      };
    </script>

    <!-- ステップ 2： Captcha JS ファイルを動的に読み込みます。 -->
    <script
      type="text/javascript"
      src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
    ></script>
  </head>

  <body>
    <!-- CAPTCHA ウィジェット用に予約されたコンテナ。以下の element パラメーターと一致する必要があります。 -->
    <div id="captcha-element"></div>

    <!-- トリガーボタン。ポップアップモードでは、これをクリックすると CAPTCHA ダイアログボックスが開きます。 -->
    <button id="button" class="btn">ログオン</button>

    <!-- ステップ 3： ページの本文の準備ができた後、Captcha を初期化します。 -->
    <script type="text/javascript">
      var captcha;
      window.initAliyunCaptcha({
        // シナリオ作成後、認証シナリオリストから取得します。
        SceneId: "xxxxxx",
        // popup：ボタンクリックでトリガーされるダイアログボックス。
        // embed：ウィジェットが常にページに表示される。
        mode: "popup",
        // HTML 内の予約されたコンテナ要素と一致する必要があります。
        element: "#captcha-element",
        // CAPTCHA ダイアログボックスまたは No-captcha 認証をトリガーする要素。
        button: "#button",
        // 認証が成功したときに呼び出されます。captchaVerifyParam はサーバーサイドの検証に必須です。
        success: function (captchaVerifyParam) {
          // captchaVerifyParam をバックエンドに送信します。
          // バックエンドは Captcha 2.0 のサーバーサイド API を呼び出して検証します。
          // 検証結果に基づいてビジネスロジックを処理します。
          // 再認証が必要な場合は、initAliyunCaptcha 初期化メソッドを呼び出して Captcha を再初期化します。
        },
        // 認証が失敗したときに呼び出されます。Captcha は有効期間内に自動的に再試行します。
        fail: function (result) {
          // result には失敗の詳細が含まれます。
          // 一時的な失敗に対しては操作は不要です — Captcha は自動的にリフレッシュします。
          console.error(result);
        },
        // Captcha が正常に初期化された後に呼び出されます。後で使用するためにインスタンスを保存します。
        getInstance: function (instance) {
          captcha = instance;
        },
        // スライダー検証およびクリック検証のトリガーボックスの幅と高さ (px)。
        // 最小幅：320 px。320 未満の値は無視され、320 が代わりに使用されます。
        // パズル CAPTCHA または画像修復検証には適用されません。
        slideStyle: {
          width: 360,
          height: 40,
        },
        // その他のパラメーターについては、以下のパラメーターリファレンスをご参照ください。
      });
    </script>
  </body>
</html>

パラメーターリファレンス

AliyunCaptchaConfig パラメーター

これらのパラメーターは、Captcha JS ファイルが読み込まれる前に定義してください。

パラメーター	タイプ	必須	デフォルト	説明
`region`	文字列	はい	`cn`	Captcha インスタンスのリージョン。有効な値：`cn` (中国本土)、`sgp` (シンガポール)。クライアントは、対応するコントロールプレーンに動作およびデバイスデータを送信します。サーバーサイドのエンドポイントは一致している必要があります。
`prefix`	文字列	はい	なし	Captcha インスタンスの ID プレフィックス。Captcha 2.0 をアクティベートした後、コンソールの [概要] > 累計アクティベーション時間 > ID プレフィックスからこの値を取得します。

initAliyunCaptcha パラメーター

ページの読み込み後に initAliyunCaptcha を呼び出します。以下の表は、最も一般的に使用されるパラメーターをリストしています。

一般的に使用されるパラメーター

パラメーター	タイプ	必須	デフォルト	説明
`SceneId`	文字列	はい	なし	シナリオ ID。認証シナリオを作成した後にこの値を取得します。
`mode`	文字列	はい	なし	レンダリングモード。`popup`：トリガーされるとダイアログボックスが表示されます。`embed`：ウィジェットが常に表示されます。No-captcha 認証には `popup` が必要です。
`element`	文字列	はい	なし	Captcha がレンダリングされる予約済みコンテナ要素の CSS セレクター。HTML 内の DOM 要素と一致する必要があります。
`button`	文字列	はい	なし	CAPTCHA ダイアログボックスまたは No-captcha 認証をトリガーする要素の CSS セレクター。
`success`	関数	はい	なし	認証成功時のコールバック。バックエンドがサーバーサイド検証 API を呼び出すために使用する `captchaVerifyParam` を受け取ります。
`fail`	関数	いいえ	なし	認証失敗時のコールバック。失敗のエラーコードを公開します。Captcha は有効期間内に自動的に再試行します。
`getInstance`	関数	はい	`getInstance`	初期化成功後に呼び出されるコールバック。Captcha インスタンスへの参照を保存するために使用します。構文は固定です：`function getInstance(instance) { captcha = instance; }`
`slideStyle`	オブジェクト	いいえ	`{ width: 360, height: 40 }`	スライダー検証およびクリック検証のトリガーボックスの幅と高さ (px)。最小幅：320 px — 320 未満の値は 320 として扱われます。パズル CAPTCHA または画像修復検証には適用されません。パズル CAPTCHA の CSS はオーバーライドしないでください。その画像サイズと答えはプリセットされており、変更できません。

追加パラメーター

パラメーター	タイプ	必須	デフォルト	説明
`language`	文字列	いいえ	`cn`	表示言語。サポートされている値については、「カスタムコピーと多言語設定」をご参照ください。
`timeout`	数値	いいえ	`5000`	単一の初期化リクエストのタイムアウト (ms)。
`rem`	番号	いいえ	`1`	CAPTCHA UI 全体をスケーリングします。正の数値を入力します：`0.5` はサイズを半分にし、`2` は 2 倍にします。主にモバイルブラウザで役立ちます。
`onError`	関数	いいえ	なし	初期化 API の失敗またはリソース読み込みタイムアウトのエラーコールバック。
`onClose`	関数	いいえ	なし	CAPTCHA ダイアログボックスが閉じられたときにトリガーされるコールバック。
`captchaLogoImg`	文字列	いいえ	なし	埋め込みモード (クリック検証、パズル CAPTCHA、画像修復検証) で、トリガーボタンの右側にある会社ロゴを置き換えます。画像 URL または base64 エンコードされたデータを受け入れます。
`dualStack`	ブール値	いいえ	`false`	デュアルスタックネットワークを有効にします。`false`：IPv4 のみ。`true`：IPv4 および IPv6。
`showErrorTip`	ブール値	いいえ	`true`	ネットワーク品質の低下によりアクセスが失敗した場合にエラーメッセージを表示します。
`delayBeforeSuccess`	ブール値	いいえ	`true`	認証成功後、`success` コールバックを 1 秒遅延させます。

インスタンスメソッド

初期化後、(getInstance を介して保存された) Captcha インスタンスを使用して、ウィジェットの可視性をプログラムで制御します。

説明

show および hide メソッドは、No-captcha モードでの最初の認証ではサポートされていません。

メソッド	説明	例	使用するタイミング
`show`	Captcha 要素とマスクを表示します。	`captcha.show()`	ボタンをクリックせずに CAPTCHA ダイアログボックスを自動的に開く場合 — 例えば、フォームがプログラムで送信されたとき。
`hide`	Captcha 要素とマスクを非表示にするか閉じます。	`captcha.hide()`	ユーザーの操作なしで CAPTCHA ダイアログボックスを自動的に閉じる場合 — 例えば、タイムアウト後。

返されるデータ

ユーザーが動作検証を完了すると、Captcha 2.0 は CAPTCHA コードとサポートパラメーターをクライアントに返します。返されたデータは、ブラウザの [ネットワーク] パネルで表示できます。レスポンス構造の詳細については、「V3 クライアントアーキテクチャによって返されるデータ」をご参照ください。

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

rem パラメーターの例

rem パラメーターを使用して、ビューポートがデフォルトのスライダー幅よりも狭いモバイルブラウザで CAPTCHA UI をスケーリングします。

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) {
  // スライダーがビューポートに収まるように UI を比例的にスケーリングします。
  const rem = Math.floor((pageWidth / customWidth) * 100) / 100;
  initCaptcha(rem);
}

次のステップ

フレームワーク固有の統合デモをダウンロードしてローカルで実行します。
サーバーサイドの検証を設定します：「サーバーサイドアクセス」
クライアントサイドのエラーコードを確認します：「クライアントサイドの初期化エラー」