キャプチャ API 仕様 JavaScript

このセクションでは、 JavaScript CAPTCHA API のメソッドとプロパティの仕様を一覧表示します。CAPTCHA JavaScript API を使用して、クライアントアプリケーションでカスタム CAPTCHA パズルを実行します。

この API は、 AWS WAF トークンの取得と使用を設定および管理するために使用するインテリジェントな脅威 API をベースにしています。「インテリジェントな脅威に対応した API 仕様」を参照してください。

AwsWafCaptcha.renderCaptcha(container, configuration)

エンドユーザーに AWS WAF CAPTCHA パズルを提示し、成功すると CAPTCHA 検証でクライアントトークンを更新します。これは CAPTCHA 統合でのみ使用できます。この呼び出しをインテリジェントな脅威に対応した API と組み合わせて使用すると、トークンの取得を管理したり、fetch コールでトークンを提供したりできます。インテリジェントな脅威に対応した API については、「インテリジェントな脅威に対応した API 仕様」を参照してください。

AWS WAF 送信する CAPTCHA インタースティシャルとは異なり、このメソッドでレンダリングされた CAPTCHA パズルでは、最初のタイトル画面なしでパズルがすぐに表示されます。

container

ページ上のターゲットとなるコンテナ要素の Element オブジェクト。これは通常、document.getElementById() または document.querySelector() を呼び出すことで取得できます。

必須: はい

タイプ: Element

設定

以下のような CAPTCHA 構成設定を含むオブジェクト。

apiKey

クライアントのドメインの許可を有効にする暗号化された API キー。 AWS WAF コンソールを使用して、クライアントドメインの API キーを生成します。1 つのキーを最大 5 つのドメインに使用できます。詳細については、JS キャプチャ API の API キーの管理 を参照してください。

必須: はい

タイプ: string

onSuccess: (wafToken: string) => void;

エンドユーザーが CAPTCHA AWS WAF パズルを正常に完了すると、有効なトークンで呼び出されます。ウェブ ACL で保護するエンドポイントに送信するリクエストでは、このトークンを使用してください。 AWS WAF トークンは、パズルの完成に最後に成功したときの証明とタイムスタンプを提供します。

必須: はい

onError?: (error: CaptchaError) => void;

CAPTCHA 操作中にエラーが発生したときに、エラーオブジェクトとともに呼び出されます。

必須: いいえ

CaptchaError クラス定義 – onError ハンドラーは、次のクラス定義を使用してエラータイプを提供します。

CaptchaError extends Error {
    kind: "internal_error" | "network_error" | "token_error" | "client_error";
    statusCode?: number;
}

• kind – 返されたエラーの種類。

• statusCode – HTTP ステータスコード (利用可能な場合)。これは、エラーが HTTP エラーに起因する場合に network_error で使用されます。

onLoad?: () => void;

新しい CAPTCHA パズルがロードされると呼び出されます。

必須: いいえ

onPuzzleTimeout?: () => void;

CAPTCHA パズルが期限切れになる前に完成しなかった場合に呼び出されます。

必須: いいえ

onPuzzleCorrect?: () => void;

CAPTCHA パズルに正しい回答が入力されると呼び出されます。

必須: いいえ

onPuzzleIncorrect?: () => void;

CAPTCHA パズルに間違った回答が入力されると呼び出されます。

必須: いいえ

defaultLocale

CAPTCHA パズルに使用するデフォルトのロケール。CAPTCHA パズルの説明書は、アラビア語 (ar-SA)、簡体字中国語 (zh-CN)、オランダ語 (nl-NL)、英語 (en-US)、フランス語 (fr-FR)、ドイツ語 (de-DE)、イタリア語 (it-IT)、日本語 (ja-JP)、ブラジルポルトガル語 (pt-BR)、スペイン語 (es-ES)、およびトルコ語 (tr-TR) で提供されています。音声による説明は、中国語と日本語 (デフォルトでは英語) を除くすべての記述言語で利用できます。デフォルト言語を変更するには、国際言語とロケールコード (例:) を指定します。ar-SA

デフォルト: エンドユーザーのブラウザで現在使用されている言語

必須: いいえ

タイプ: string

disableLanguageSelector

true に設定すると、CAPTCHA パズルの言語セレクタが非表示になります。

デフォルト: false

必須: いいえ

タイプ: boolean

dynamicWidth

true に設定すると、CAPTCHA パズルの幅はブラウザウィンドウの幅に合わせて変更されます。

デフォルト: false

必須: いいえ

タイプ: boolean

skipTitle

true に設定すると、CAPTCHA パズルのパズルタイトルに「パズルを解く」という見出しが表示されません。

デフォルト: false

必須: いいえ

タイプ: boolean