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() によって作成されたトークンを含む文字列か、トークンがまだ作成されていない場合は空の文字列のいずれかになります。

構成

このセクションでは、JavaScript リソース パラメータと grecaptcha.enterprise.render() で使用されるパラメータ、および 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	bottomright、 bottomleft、 inline	bottomright	省略可。reCAPTCHA バッジの位置を変更します。inline を使用すると、CSS で配置できます。
data-action	action			省略可。現在のアクションを説明する文字列
data-theme	theme	dark、light	light	省略可。ウィジェットのカラーテーマ
data-size	size	compact、normal	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 がエラー（通常はネットワーク接続）を検出し、接続が復元されるまで続行できないときに実行されるコールバック関数の名前。コールバックは、エラーの詳細を含む引数を受け取りません。ここで関数を指定すると、ユーザーに再試行を促す通知を行う必要があります。