JavaScript API-Referenz für reCAPTCHA

Die reCAPTCHA JavaScript API bietet die Methoden und Konfigurationsparameter, mit denen Sie reCAPTCHA-Widgets auf Webseiten mit einem Websiteschlüssel rendern und verwalten können.

reCAPTCHA JavaScript API-Methoden

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

grecaptcha.enterprise.render

Rendert den Container als reCAPTCHA-Widget und gibt die ID des neu erstellten Widgets zurück.

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 des Containers (String) oder das DOM-Element selbst an.
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. Wenn nichts angegeben ist, 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 nichts angegeben ist, wird standardmäßig die ID des ersten erstellten Widgets verwendet. Hinweis: Zur Verwendung mit Websiteschlüsseln für Kästchen.
sitekey	Geben Sie den zu schützenden reCAPTCHA-Websiteschlüssel an. Hinweis: Zur Verwendung mit punktbasierten Websiteschlüsseln.
action	Ein Objekt mit einem einzelnen Schlüssel/Wert-Paar, wobei der Wert für den Schlüssel action den Aktionsnamen angibt, der dem geschützten Element zugeordnet ist. Hinweis: Zur Verwendung mit punktbasierten Websiteschlüsseln. Beispiel: {"action": "action_name"}

Rückgabewert

Wenn der Vorgang erfolgreich ist, wird ein Promise-Objekt mit dem Token zurückgegeben.

grecaptcha.enterprise.ready

Führt Ihre Funktion aus, wenn 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 vollständig 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 nichts angegeben ist, wird standardmäßig die ID des ersten erstellten Widgets verwendet.

Rückgabewert

Ruft die Antwort des reCAPTCHA-Widgets ab. Es kann entweder ein String mit dem von grecaptcha.enterprise.execute() erstellten Token oder ein leerer String sein, wenn das Token noch nicht erstellt wurde.

Konfiguration

In diesem Abschnitt werden die JavaScript-Ressourcenparameter, die von grecaptcha.enterprise.render() verwendeten Parameter und 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 der Callback-Funktion, die ausgeführt werden soll, nachdem alle Abhängigkeiten geladen wurden.
render	onload	Optional, Standardwert. Rendert das Widget im ersten gefundenen g-recaptcha-Tag. Hinweis: Zur Verwendung mit Websiteschlüsseln für Kästchen.
	explicit	Optional. Das Widget wird nicht automatisch gerendert. Sie müssen grecaptcha.enterprise.render() aufrufen, um es programmatisch zu rendern. Hinweis: Zur Verwendung mit Websiteschlüsseln für Kästchen.
	siteKey	Bei Verwendung mit bewertungsbasierten Websiteschlüsseln ist dieser Parameter nicht optional. Der Wert siteKey gibt den zugehörigen bewertungsbasierten Websiteschlüssel an. Hinweis: Nur für die Verwendung mit bewertungsbasierten Websiteschlüsseln. Bei Verwendung mit Websiteschlüsseln für Kästchen 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. reCAPTCHA-Logo neu positionieren 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 Callback empfängt 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.