JavaScript API-Referenz für reCAPTCHA Enterprise

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

reCAPTCHA Enterprise JavaScript API-Methoden

In diesem Abschnitt werden die Syntax und die Parameter von reCAPTCHA Enterprise 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 jedem konfigurierbaren Parameter 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 keine Angabe erfolgt, wird standardmäßig die ID des ersten erstellten Widgets verwendet.

Rückgabewert

Gibt keinen Wert zurück.

grecaptcha.enterprise.execute

Ruft programmatisch die reCAPTCHA Enterprise-Prüfung 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:Wird mit Kästchen-Websiteschlüsseln verwendet.
sitekey	Geben Sie den zu schützenden reCAPTCHA-Websiteschlüssel an. Hinweis: Dieses Feld kann mit wertbezogenen Websiteschlüsseln verwendet werden.
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: Dieses Feld kann mit wertbezogenen Websiteschlüsseln verwendet werden. Beispiel: {"action": "action_name"}

Rückgabewert

Bei Erfolg wird ein Promise-Objekt zurückgegeben, das das Token enthält.

grecaptcha.enterprise.ready

Führt die Funktion aus, wenn die reCAPTCHA Enterprise-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 wurde.

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. Dies 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 Enterprise einfügen müssen.

Weitere Informationen zur Verwendung dieser Parameter finden Sie in den Beispielen unter reCAPTCHA-Widget im Front-End 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	Optionaler Standardwert. Stellt das Widget im ersten gefundenen g-recaptcha-Tag dar. Hinweis:Wird mit Kästchen-Websiteschlüsseln verwendet.
	explicit	Optional. Das Widget wird nicht automatisch gerendert. Du musst grecaptcha.enterprise.render() aufrufen, um es programmatisch zu rendern. Hinweis:Wird mit Kästchen-Websiteschlüsseln verwendet.
	siteKey	Bei Verwendung mit auf Punktzahlen basierenden Websiteschlüsseln ist dieser Parameter nicht optional. Der Wert siteKey gibt den auf Punktzahlen basierenden Websiteschlüssel an. Hinweis:Kann nur mit auf Punktzahlen basierenden Websiteschlüsseln verwendet werden. Bei Verwendung mit Kästchen-Websiteschlüsseln wird das Skript 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. Positioniere 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	Integer	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. Wenn Sie hier eine Funktion angeben, sind Sie dafür verantwortlich, den Nutzer darüber zu informieren, dass er es noch einmal versuchen soll.