reCAPTCHA の JavaScript API リファレンス

このページでは、reCAPTCHA JavaScript API のメソッドと、reCAPTCHA キー(サイトキー)を使用してウェブページをレンダリングする際に使用できる構成パラメータについて説明します。

reCAPTCHA JavaScript API メソッド

このセクションでは、reCAPTCHA JavaScript API メソッドの構文とパラメータについて説明します。

grecaptcha.enterprise.render

コンテナを reCAPTCHA ウィジェットとしてレンダリングし、新しく作成されたウィジェットの ID を返します。

構文

grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number

メソッドのパラメータ

パラメータ 説明
container コンテナ reCAPTCHA ウィジェットをレンダリングするための HTML 要素。コンテナの ID(文字列)または DOM 要素自体を指定します。
parameters

パラメータを key=value ペアとして含むオブジェクト。例: {"sitekey": "your_site_key", "action": "login", "theme": "dark"}

構成可能な各パラメータの詳細については、属性とパラメータをご覧ください。

戻り値

新しく作成されたウィジェットの ID を返します。

grecaptcha.enterprise.reset

reCAPTCHA ウィジェットをリセットします。

構文

grecaptcha.enterprise.reset(widget_id: number): void

パラメータ

パラメータ 説明
widget_id 省略可。grecaptcha.enterprise.render() から返されるウィジェット ID。指定しない場合、作成された最初のウィジェットの ID がデフォルトになります。

戻り値

値は返しません。

grecaptcha.enterprise.execute

reCAPTCHA による確認をプログラムで呼び出します。

構文

grecaptcha.enterprise.execute(widget_id: number): Promise<string>
grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>

パラメータ

パラメータ 説明
widget_id 省略可。grecaptcha.enterprise.render() から返されるウィジェット ID。

指定しない場合、作成された最初のウィジェットの ID がデフォルトになります。

sitekey

保護する reCAPTCHA サイトキーを指定します。

action Key-Value ペアを 1 つ含むオブジェクト。action キーの値は、保護された要素に関連付けられたアクション名を指定します。

例: {"action": "action_name"}

戻り値

成功した場合はトークンを含む Promise オブジェクトを返します。

grecaptcha.enterprise.ready

reCAPTCHA JavaScript ライブラリが読み込まれるときに関数を実行します。

構文

grecaptcha.enterprise.ready(callback: function): void

パラメータ

パラメータ 説明
callback reCAPTCHA ライブラリの読み込みが完了したときに呼び出す関数。

戻り値

値は返しません。

grecaptcha.enterprise.getResponse

reCAPTCHA ウィジェットのレスポンスを取得します。

構文

grecaptcha.enterprise.getResponse(widget_id: number): string

パラメータ

パラメータ 説明
widget_id 省略可。grecaptcha.enterprise.render() から返されるウィジェット ID。 指定しない場合、作成された最初のウィジェットの ID がデフォルトになります。

戻り値

reCAPTCHA ウィジェットのレスポンスを取得します。grecaptcha.enterprise.execute() によって作成されたトークンを含む文字列か、トークンがまだ作成されていない場合は空の文字列のいずれかになります。

構成

このセクションでは、grecaptcha.enterprise.render() で使用される JavaScript リソース パラメータとパラメータ、および g-recaptcha ウィジェットの属性について説明します。

JavaScript リソース(enterprise.js)パラメータ

次の表に、reCAPTCHA を使用する際に含める必要がある JavaScript リソース(enterprise.js)のパラメータを示します。

これらのパラメータの使用方法の詳細については、フロントエンドで reCAPTCHA ウィジェットをレンダリングするの例をご覧ください。

パラメータ 説明
onload callback 省略可。すべての依存関係が読み込まれると実行されるコールバック関数の名前。
render onload

(省略可)デフォルト値最初に検出された g-recaptcha タグでウィジェットをレンダリングします。

explicit

省略可。ウィジェットを自動的にレンダリングしません。プログラムでレンダリングするには、grecaptcha.enterprise.render() を呼び出す必要があります。

siteKey

スコアベースのサイトキーで使用する場合、このパラメータは省略可能ではありません。 値 siteKey は、関連付けられたスコアベースのサイトキーを指定します。

hl 言語コードをご覧ください 省略可。ウィジェットを特定の言語で強制的にレンダリングします。 指定されていない場合はユーザーの言語を自動検出します。

g-recaptcha タグの属性と grecaptcha.enterprise.render() パラメータ

次の表に、g-recaptcha タグの属性と対応する grecaptcha.enterprise.render() パラメータを示します。

g-recaptcha タグ属性 grecaptcha.enterprise.render()パラメータ 使用できる値 デフォルト 説明
data-sitekey sitekey reCAPTCHA キー
data-badge badge bottomrightbottomleftinline bottomright 省略可。reCAPTCHA バッジの位置を変更します。inline を使用すると、CSS でコードを配置できます。
data-action action 省略可。現在のアクションを説明する文字列
data-theme theme dark, light light 省略可。ウィジェットのカラーテーマ
data-size size compactnormal normal 省略可。ウィジェットのサイズ
data-tabindex tabindex 整数 0 省略可。ウィジェットとチャレンジの tabindexページ内の他の要素が tabindex を使用する場合、ユーザー ナビゲーションを容易にするために設定する必要があります。
data-callback callback 文字列 該当なし 省略可。ユーザーが成功の応答を送信したときに実行されるコールバック関数の名前。g-recaptcha-response トークンがコールバックに渡されます。
data-expired-callback expired-callback 文字列 該当なし 省略可。コールバック関数の名前。reCAPTCHA レスポンスの有効期限が切れ、ユーザーが再確認する必要があるときに実行されます。
data-error-callback error-callback 文字列 該当なし 省略可。reCAPTCHA がエラー(通常はネットワーク接続)を検出し、接続が復元されるまで続行できないときに実行されるコールバック関数の名前。コールバックは、エラーの詳細を含む引数を受け取りません。ここで関数を指定すると、ユーザーに再試行を促す通知を行う必要があります。