> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# RECAPTCHAV3- (Google reCAPTCHA)

> Google reCAPTCHA V3 im Template einbinden: das Skript laden, den Token übergeben, das Ergebnis der Prüfung abfragen und im Fehlerfall die Antwort von Google auswerten.

Google reCAPTCHA V3 stellt dem Besucher keine Aufgabe, sondern beobachtet sein Verhalten und vergibt dafür eine Punktzahl zwischen 0 und 1. Der Shop holt diese Punktzahl bei Google ab und entscheidet anhand eines konfigurierten Schwellenwerts, ob er den Besucher für einen Menschen hält.

Im Template läuft das in drei Schritten ab: Sie laden das Skript von Google, übergeben den von Google erzeugten Token an den Shop, und fragen anschließend das Ergebnis ab. Die sechs `RECAPTCHAV3-`Tags decken genau diese drei Schritte ab.

Wegweiser: [Captcha-Schutz](https://dokumentation.websale.de/v8s/upload-modul/formulare-mit-inquiry4/konfigurationsdatei.md)

Alle Tags dieser Seite sind auf allen Templates zulässig.

Friendly Captcha ist der zweite im Shopsystem verfügbare Anbieter. Die Tags dort heißen anders, arbeiten aber nach genau demselben Muster.

Referenz: [FRIENDLYCAPTCHAV1- (Friendly Captcha)](https://dokumentation.websale.de/v8s/referenz/tags/friendlycaptchav1.md)

## Das Skript von Google laden

Zwei Tags liefern die Angaben, die das Skript braucht.

| Tag | Liefert |
| - | - |
| `RECAPTCHAV3-APIUrl` | die konfigurierte Adresse der reCAPTCHA-Schnittstelle |
| `RECAPTCHAV3-SiteKey` | den konfigurierten Website-Schlüssel |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>
```

Beide Werte stammen aus der Shopkonfiguration. Schreiben Sie sie nicht fest in das Template, sonst bricht die Einbindung, sobald der Schlüssel gewechselt wird oder ein Subshop einen eigenen verwendet.

Im Shopsystem greifen sie auch als Klammerung, und zwar wenn der jeweilige Wert konfiguriert ist. Damit lässt sich die ganze Einbindung sauber ausblenden, wenn reCAPTCHA für diesen Shop nicht eingerichtet ist.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-SiteKey}
   <script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>
{/RECAPTCHAV3-SiteKey}
```

## Den Token an den Shop übergeben

Google erzeugt im Browser einen Token. Diesen Token muss Ihr Formular unter dem Namen `ws_recaptchav3_token` an den Shop schicken, sonst kann der Shop nichts prüfen.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form method="post" action="~FORM-Inquiry~">
   <input type="hidden" name="ws_recaptchav3_token" value="">
   ...
</form>

<script>
   grecaptcha.ready(function() {
      grecaptcha.execute('~RECAPTCHAV3-SiteKey~', { action: 'homepage' })
         .then(function(token) {
            document.querySelector("[name='ws_recaptchav3_token']").value = token;
         });
   });
</script>
```

> [!WARNING]
>
> Der Feldname `ws_recaptchav3_token` ist fest vorgegeben und hat kein eigenes Tag. Schreiben Sie ihn genau so. Ein fehlender oder leerer Token führt zum Antwortcode 200, die Prüfung gilt dann als nicht bestanden.

Ein Token von Google ist kurzlebig. Holen Sie ihn deshalb erst unmittelbar vor dem Absenden, nicht beim Seitenaufbau, wenn zwischen Aufbau und Absenden viel Zeit vergehen kann.

## Das Ergebnis abfragen

Zwei Klammerungen fragen das Ergebnis ab. Der Unterschied liegt darin, wie oft geprüft wird.

| Tag | Prüft |
| - | - |
| `RECAPTCHAV3-PassedAlways` | bei jedem Seitenaufruf erneut |
| `RECAPTCHAV3-PassedOnce` | einmal je Sitzung, danach gilt das gespeicherte Ergebnis |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-PassedOnce}
   <a href="~ERP-DownloadLink~">Preisliste herunterladen</a>
{/RECAPTCHAV3-PassedOnce}

{!RECAPTCHAV3-PassedOnce}
   <p>Bitte bestätigen Sie, dass Sie kein Roboter sind.</p>
{/!RECAPTCHAV3-PassedOnce}
```

> [!WARNING]
>
> Beide Tags sind keine passiven Abfragen. Beim Auswerten stellt das Shopsystem eine Anfrage an Google und wartet auf die Antwort. Setzen Sie sie deshalb nur dort, wo das Ergebnis gebraucht wird, und nicht vorsorglich auf jeder Seite. Jede tatsächlich durchgeführte Prüfung wird im Shopsystem mitgezählt.
>
> Hat `RECAPTCHAV3-PassedOnce` einmal ein negatives Ergebnis in der Sitzung gespeichert, liefert es für den Rest der Sitzung weiterhin "nicht bestanden" und fragt nicht erneut bei Google nach. Der Besucher kommt aus diesem Zustand nicht allein heraus. Verwenden Sie an der Stelle, an der er es erneut versuchen soll, zusätzlich `RECAPTCHAV3-PassedAlways`. Eine damit erzielte erfolgreiche Prüfung hebt das gespeicherte negative Ergebnis wieder auf.

`RECAPTCHAV3-PassedAlways` prüft je Seitenaufruf genau einmal. Mehrfaches Setzen auf derselben Seite erzeugt also keine zweite Anfrage, sondern verwendet das Ergebnis des ersten Tags weiter.

Bestanden ist die Prüfung, wenn die von Google gelieferte Punktzahl **größer** als der konfigurierte Mindestwert ist. Eine Punktzahl, die genau dem Mindestwert entspricht, gilt als nicht bestanden.

> [!WARNING]
>
> Ist Google nicht erreichbar, melden beide Tags "nicht bestanden". Eine in der Konfiguration hinterlegte Nachsicht bei technischen Störungen greift an dieser Stelle nicht. Planen Sie deshalb für wichtige Funktionen einen Weg ein, der auch ohne erfolgreiche Prüfung weiterführt.

Richtig ist `RECAPTCHAV3-`.

## Fehler nachvollziehen

Nach einer Prüfung stehen zwei Tags für die Fehlersuche bereit.

| Tag | Liefert |
| - | - |
| `RECAPTCHAV3-LastResponseCode` | den technischen Statuscode der letzten Prüfung |
| `RECAPTCHAV3-LastPlainResponse` | die unveränderte Antwort von Google |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{RECAPTCHAV3-PassedAlways}
   Prüfung bestanden.
{/RECAPTCHAV3-PassedAlways}

{!RECAPTCHAV3-PassedAlways}
   Prüfung nicht bestanden, Code ~RECAPTCHAV3-LastResponseCode~.
{/!RECAPTCHAV3-PassedAlways}
```

> [!WARNING]
>
> Beide Tags beziehen sich auf die **letzte** Prüfung. Sie müssen im Template deshalb **nach** `RECAPTCHAV3-PassedOnce` oder `RECAPTCHAV3-PassedAlways` stehen. Davor hat noch keine Prüfung stattgefunden, und der Code ist 0, was fälschlich wie ein bestandener Test aussieht.

### Die Antwortcodes

Das Shopsystem unterscheidet darüber hinaus, woran es gelegen hat.

| Code | Bedeutung |
| - | - |
| 0 | Prüfung bestanden |
| 1 | in diesem Seitenaufruf bereits geprüft und nicht bestanden |
| 2 | in dieser Sitzung bereits geprüft und nicht bestanden |
| 3 | Google hat geantwortet, die Punktzahl reicht nicht |
| 200 | kein Token übergeben, das Feld `ws_recaptchav3_token` fehlt oder ist leer |
| 201 | in der Konfiguration fehlt die Prüfadresse |
| 202 | in der Konfiguration fehlt der geheime Schlüssel |
| 300 | die Anfrage an Google ist fehlgeschlagen |
| 301 | Google hat nichts zurückgeliefert |
| 302 | die Antwort von Google ließ sich nicht auswerten |
| 400 | das Shopsystem konnte die Anfrage nicht vorbereiten |

Die Codes 1 und 2 bedeuten nicht, dass gerade geprüft wurde. Sie sagen, dass ein früheres negatives Ergebnis weiterverwendet wurde. Code 2 kommt nur von `RECAPTCHAV3-PassedOnce`, Code 1 nur von `RECAPTCHAV3-PassedAlways` bei einem zweiten Vorkommen auf derselben Seite.

Die Codes 201 und 202 weisen auf eine unvollständige Shopkonfiguration hin, nicht auf ein Verhalten des Besuchers.

`RECAPTCHAV3-LastPlainResponse` liefert die Antwort von Google als JSON, unverändert. Darin stehen unter anderem die Punktzahl und der Aktionsname. Zur Weiterverarbeitung im Template übergeben Sie den Inhalt an die JSON-Schnittstelle.

Referenz: [EJD- (JSON-Schnittstelle)](https://dokumentation.websale.de/v8s/referenz/tags/ejd.md)

> [!WARNING]
>
> Geben Sie `RECAPTCHAV3-LastPlainResponse` nicht in einer öffentlich sichtbaren Seite aus. Die Antwort enthält technische Angaben zum Shop, die niemanden außer Ihnen etwas angehen. Für die Fehlersuche eignet sich eine eigene, geschützte Seite.

## Die Tags im Überblick

| Tag | Einzel-Tag | Bereichs-Tag | negatives Bereichs-Tag | Schleifen-Tag |
| - | - | - | - | - |
| `RECAPTCHAV3-APIUrl` | ja | ja | ja | – |
| `RECAPTCHAV3-SiteKey` | ja | ja | ja | – |
| `RECAPTCHAV3-PassedOnce` | – | ja | ja | – |
| `RECAPTCHAV3-PassedAlways` | – | ja | ja | – |
| `RECAPTCHAV3-LastPlainResponse` | ja | ja | ja | – |
| `RECAPTCHAV3-LastResponseCode` | ja | – | – | – |

Alle sechs Tags sind auf allen Templates zulässig. `RECAPTCHAV3-LastResponseCode` gilt als Klammerung als ungültiges Tag.

## Verwandte Themen

* Wegweiser: Captcha-Schutz
* Referenz: [FRIENDLYCAPTCHAV1- (Friendly Captcha)](https://dokumentation.websale.de/v8s/referenz/tags/friendlycaptchav1.md)
* Referenz: [EJD- (JSON-Schnittstelle)](https://dokumentation.websale.de/v8s/referenz/tags/ejd.md)
* Referenz: Abschnitt Captcha in der Shopkonfiguration


## Related topics

- [Externe Dienste und Schnittstellen](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/externe-dienste-und-schnittstellen.md)
- [Validierungs- und Prüfservices](https://dokumentation.websale.de/konfiguration/validierungs-und-prufservices.md)
- [Bestelldetails anzeigen ohne Login](https://dokumentation.websale.de/v8s/weitere-funktionen-im-bestellprozess-kontext/bestelldetails-anzeigen-ohne-login.md)
- [Google reCAPTCHA erst nach Einwilligung laden](https://dokumentation.websale.de/v8s/anwendungsbeispiele/appex-recaptcha-mit-einwilligung.md)
- [security - Sicherheitsregeln](https://dokumentation.websale.de/konfiguration/security-sicherheitsregeln.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.