JavaScript API-Referenz für reCAPTCHA

Auf dieser Seite werden Methoden der reCAPTCHA JavaScript API und ihre Konfigurationsparameter beschrieben, mit denen Sie die Webseiten mit einem reCAPTCHA-Schlüssel (Websiteschlüssel) rendern können.

reCAPTCHA JavaScript API-Methoden

In diesem Abschnitt werden die Syntax und die Parameter von reCAPTCHA JavaScript API-Methoden beschrieben.

grecaptcha.enterprise.render

Rendert den Container als reCAPTCHA-Widget und gibt die ID der neuen erstellten Widget.

Syntax

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

Methodenparameter

Parameter	Beschreibung
container	Das HTML-Element, das das reCAPTCHA-Widget rendert. Geben Sie entweder die ID an des Containers (String) oder des DOM-Elements selbst.
parameters	Ein Objekt, das Parameter als Schlüssel/Wert-Paare enthält, z. B. {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Weitere Informationen zu den einzelnen konfigurierbaren Parametern finden Sie unter Attribute und Parameter.

Rückgabewert

Gibt die ID des neu erstellten Widgets zurück.

grecaptcha.enterprise.reset

Setzt das reCAPTCHA-Widget zurück.

Syntax

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

Parameter

Parameter	Beschreibung
widget_id	Optional. Von grecaptcha.enterprise.render() zurückgegebene Widget-ID. Falls nicht wird standardmäßig die ID des ersten erstellten Widgets verwendet.

Rückgabewert

Gibt keinen Wert zurück.

grecaptcha.enterprise.execute

Ruft die reCAPTCHA-Überprüfung programmatisch auf.

Syntax

grecaptcha.enterprise.execute(widget_id: number): Promise<string>

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

Parameter

Parameter	Beschreibung
widget_id	Optional. Von grecaptcha.enterprise.render() zurückgegebene Widget-ID. Wenn keine Angabe erfolgt, wird standardmäßig die ID des ersten erstellten Widgets verwendet. Hinweis: Zur Verwendung mit Kästchen-Websiteschlüsseln.
sitekey	Geben Sie den zu schützenden reCAPTCHA-Websiteschlüssel an. Hinweis:Wird mit wertbasierten Websiteschlüsseln verwendet.
action	Ein Objekt mit einem einzelnen Schlüssel/Wert-Paar, wobei der Wert für Der Schlüssel action gibt den Aktionsnamen an, der mit dem geschütztes Element. Hinweis:Wird mit wertbasierten Websiteschlüsseln verwendet. Beispiel: {"action": "action_name"}

Rückgabewert

Bei Erfolg wird ein Promise-Objekt mit dem Token zurückgegeben.

grecaptcha.enterprise.ready

Führt die Funktion aus, während die reCAPTCHA-JavaScript-Bibliothek geladen wird.

Syntax

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

Parameter

Parameter	Beschreibung
callback	Die Funktion, die aufgerufen werden soll, wenn die reCAPTCHA-Bibliothek fertig geladen ist.

Rückgabewert

Gibt keinen Wert zurück.

grecaptcha.enterprise.getResponse

Ruft die Antwort für das reCAPTCHA-Widget ab.

Syntax

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

Parameter

Parameter	Beschreibung
widget_id	Optional. Von grecaptcha.enterprise.render() zurückgegebene Widget-ID. Wenn keine Angabe erfolgt, wird standardmäßig die ID des ersten erstellten Widgets verwendet.

Rückgabewert

Ruft die Antwort des reCAPTCHA-Widgets ab. Es kann sich dabei um einen String mit dem von grecaptcha.enterprise.execute() erstellten Token oder um einen leeren String handeln, wenn das Token noch nicht erstellt wurde.

Konfiguration

In diesem Abschnitt werden die JavaScript-Ressourcenparameter und die von grecaptcha.enterprise.render() verwendeten Parameter sowie die Attribute des g-recaptcha-Widgets beschrieben.

JavaScript-Ressourcenparameter (enterprise.js)

In der folgenden Tabelle sind die Parameter der JavaScript-Ressource (enterprise.js) aufgeführt. die Sie bei der Verwendung von reCAPTCHA angeben müssen.

Weitere Informationen zur Verwendung dieser Parameter finden Sie in den Beispielen unter reCAPTCHA-Widget im Frontend rendern.

Parameter	Wert	Beschreibung
onload	callback	Optional. Der Name Ihrer Callback-Funktion, die ausgeführt werden soll, nachdem alle Abhängigkeiten geladen wurden.
render	onload	Optional, Standardwert. Das Widget wird im ersten gefundenen g-recaptcha-Tag gerendert. Hinweis:Dieses Attribut wird mit Kästchen-Websiteschlüsseln verwendet.
	explicit	Optional. Das Widget wird nicht automatisch gerendert. Sie müssen grecaptcha.enterprise.render() aufrufen, um es programmatisch zu rendern. Hinweis: Zur Verwendung mit Kästchen-Websiteschlüsseln.
	siteKey	Bei Verwendung mit wertbasierten Websiteschlüsseln ist dieser Parameter nicht optional. Der Wert siteKey gibt den verknüpften punktzahlbasierten Websiteschlüssel an. Hinweis: Nur für die Verwendung mit punktzahlbasierten Websiteschlüsseln. Bei Verwendung mit Kästchen-Websiteschlüsseln wird das Script nicht geladen.
hl	Siehe Sprachcodes.	Optional. Erzwingt das Rendern des Widgets in einer bestimmten Sprache. Erkennt automatisch die Sprache des Nutzers.

g-recaptcha-Tag-Attribute und grecaptcha.enterprise.render()-Parameter

In der folgenden Tabelle sind die Tag-Attribute g-recaptcha und die entsprechenden grecaptcha.enterprise.render()-Parameter aufgeführt.

g-recaptcha-Tag-Attribut	grecaptcha.enterprise.render() Parameter	Zulässige Werte	Standard	Beschreibung
data-sitekey	sitekey			reCAPTCHA-Schlüssel
data-badge	badge	bottomright, bottomleft, inline	bottomright	Optional. Platzieren Sie das reCAPTCHA-Logo neu. Mit inline können Sie es mit CSS positionieren.
data-action	action			Optional. String, die die aktuelle Aktion beschreibt.
data-theme	theme	dark, light	light	Optional. Das Farbdesign des Widgets.
data-size	size	compact, normal	normal	Optional. Die Größe des Widgets
data-tabindex	tabindex	Ganzzahl	0	Optional. Der Tabindex des Widgets und der Challenge. Wenn andere Elemente auf Ihrer Seite tabindex verwenden, sollte sie so eingestellt werden, dass eine einfachere Navigation möglich ist.
data-callback	callback	String	–	Optional. Der Name Ihrer Callback-Funktion, die ausgeführt wird, wenn der Nutzer eine erfolgreiche Antwort sendet. Das g-recaptcha-response-Token wird an Ihren Callback übergeben.
data-expired-callback	expired-callback	String	–	Optional. Der Name Ihrer Callback-Funktion, die ausgeführt wird, wenn die reCAPTCHA-Antwort abläuft und der Nutzer sich noch einmal verifizieren muss.
data-error-callback	error-callback	String	–	Optional. Der Name Ihrer Callback-Funktion, die ausgeführt wird, wenn reCAPTCHA auf einen Fehler stößt (in der Regel die Netzwerkverbindung) und nicht fortfahren kann, bis die Verbindung wieder hergestellt ist. Der Rückruf erhält keine Argumente mit Fehlerdetails. Wenn Sie hier eine Funktion angeben, sind Sie dafür verantwortlich, den Nutzer darüber zu informieren, dass er es noch einmal versuchen soll.