> ## 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.

# FRIENDLYCAPTCHAV1- (Friendly Captcha)

> Das Friendly-Captcha-Widget im Template einbinden, die Prüfung auslösen und das Ergebnis auswerten. Mit der vollständigen Liste der Statuscodes.

Friendly Captcha schützt Formulare vor automatisiertem Missbrauch, ohne dem Besucher eine Aufgabe zu stellen. Der Browser löst im Hintergrund ein Rechenrätsel und legt die Lösung in ein verstecktes Feld des Formulars. Beim Absenden prüft WEBSALE V8s diese Lösung beim Friendly-Captcha-Dienst nach.

Im Template brauchen Sie dafür drei Dinge: das Widget, das die Lösung erzeugt, die Auslösung der Prüfung, und die Auswertung des Ergebnisses. Für jeden dieser Schritte gibt es Tags.

Zugangsdaten und Adressen des Dienstes stehen in der Shopkonfiguration. Von den vier hinterlegten Werten geben nur zwei Tags aus, nämlich die öffentlichen. Der API-Schlüssel und die Prüfadresse bleiben serverseitig und haben bewusst kein Tag.

Wegweiser: [Spamschutz für Formulare](https://dokumentation.websale.de/v8s/upload-modul/formulare-mit-inquiry4/globale-konfiguration.md) · Referenz: [Shopkonfiguration shop.config](https://dokumentation.websale.de/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/grundlagen-und-technik.md)

## Das Widget einbinden

Zwei Einzel-Tags liefern die Werte, die das Friendly-Captcha-Skript im Browser benötigt.

| Tag | Liefert |
| - | - |
| `FRIENDLYCAPTCHAV1-ApplicationID` | die hinterlegte ApplicationID, im Widget der Sitekey |
| `FRIENDLYCAPTCHAV1-APIUrl` | die hinterlegte Adresse der Friendly-Captcha-API |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<form action="~FORM-Search~" method="post">
   ...
   <div class="frc-captcha"
        data-sitekey="~FRIENDLYCAPTCHAV1-ApplicationID~"
        data-puzzle-endpoint="~FRIENDLYCAPTCHAV1-APIUrl~"
        data-start="focus"></div>

   <button type="submit">Absenden</button>
</form>
```

> [!WARNING]
>
> Das Widget gehört innerhalb des `form`-Elements. Es schreibt seine Lösung in ein verstecktes Feld mit dem Namen `frc-captcha-solution`, und genau dieses Feld liest WEBSALE V8s beim Absenden aus. Steht das Widget außerhalb des Formulars, wird das Feld nicht mitgeschickt, und die Prüfung schlägt mit dem Code 200 fehl.

> [!NOTE]
>
> Beide Tags arbeiten auch als Klammerung. Sie greifen, wenn der jeweilige Wert in der Shopkonfiguration hinterlegt ist. So blenden Sie das Widget nur dort ein, wo Friendly Captcha tatsächlich eingerichtet ist:
>
> ```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
> {FRIENDLYCAPTCHAV1-ApplicationID}
>    <div class="frc-captcha" data-sitekey="~FRIENDLYCAPTCHAV1-ApplicationID~" ...></div>
> {/FRIENDLYCAPTCHAV1-ApplicationID}
> ```

## Die Prüfung auslösen

Zwei Klammerungen lösen die Prüfung aus und zeigen ihren Bereich, wenn sie bestanden wurde.

| Tag | Prüft |
| - | - |
| `FRIENDLYCAPTCHAV1-PassedOnce` | einmal je Sitzung, ein bestandenes Ergebnis gilt danach weiter |
| `FRIENDLYCAPTCHAV1-PassedAlways` | bei jedem Seitenaufruf neu |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{FRIENDLYCAPTCHAV1-PassedAlways}
   <p>Vielen Dank, Ihre Anfrage wurde abgeschickt.</p>
{/FRIENDLYCAPTCHAV1-PassedAlways}

{!FRIENDLYCAPTCHAV1-PassedAlways}
   <p>Die Prüfung ist fehlgeschlagen. Bitte versuchen Sie es erneut.</p>
{/!FRIENDLYCAPTCHAV1-PassedAlways}
```

> [!WARNING]
>
> Diese beiden Tags fragen kein Ergebnis ab, sie führen die Prüfung durch. Jedes von ihnen löst beim ersten Auswerten auf einer Seite eine Anfrage an den Friendly-Captcha-Dienst aus. Setzen Sie sie deshalb nur dort ein, wo tatsächlich ein abgeschicktes Formular auszuwerten ist, und nicht vorsorglich in einem Seitenkopf.

Innerhalb eines Seitenaufrufs wird höchstens einmal angefragt. Weitere Auswertungen desselben Tags oder seines negativen Gegenstücks verwenden das gemerkte Ergebnis. Sie können den Bereich und den Gegenbereich also gefahrlos beide im Template stehen lassen.

> [!WARNING]
>
> Ist der Friendly-Captcha-Dienst nicht erreichbar, gilt die Prüfung als nicht bestanden. Die Einstellung `fail-open`, die es für die Captcha-Prüfung an anderen Stellen des Shopsystems gibt, wirkt auf diese beiden Tags nicht. Ein Formular, das allein über diese Klammerung abgesichert ist, ist bei einer Störung des Dienstes für niemanden mehr benutzbar. Planen Sie dafür einen erkennbaren Hinweis im Gegenbereich ein.

### Wann welches der beiden

`PassedOnce` ist für Fälle gedacht, in denen ein Besucher innerhalb einer Sitzung mehrere geschützte Formulare ausfüllt. Er löst das Rätsel einmal, danach gilt er als geprüft. Das ist bequem, schützt aber nur den ersten Absendevorgang.

`PassedAlways` prüft jedes Absenden einzeln. Das ist die Wahl für Formulare, die einzeln missbraucht werden können, beispielsweise ein Kontaktformular oder eine Anfrage.

> [!WARNING]
>
> `PassedOnce` merkt sich nicht nur das bestandene Ergebnis, sondern auch das gescheiterte, und fragt danach nicht mehr nach. Ist die erste Prüfung einer Sitzung fehlgeschlagen, liefert das Tag für den Rest der Sitzung den Code 2, egal was der Besucher danach eingibt. Das trifft auch den harmlosen Fall, dass ein Formular einmal ohne gelöstes Rätsel abgeschickt wurde.
>
> Der einzige Weg zurück führt über `PassedAlways`. Dieses Tag fragt erneut an und setzt bei Erfolg auch die Sitzung auf bestanden. Wenn Sie `PassedOnce` verwenden, sollten Sie das wiederholte Absenden desselben Formulars deshalb über `PassedAlways` absichern.

## Das Ergebnis auswerten

Für die Fehlersuche gibt es zwei weitere Tags.

| Tag | Liefert |
| - | - |
| `FRIENDLYCAPTCHAV1-LastResponseCode` | den internen Statuscode der letzten Prüfung |
| `FRIENDLYCAPTCHAV1-LastPlainResponse` | die unveränderte Antwort des Friendly-Captcha-Dienstes |

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{FRIENDLYCAPTCHAV1-PassedAlways}
   <p>Geprüft.</p>
{/FRIENDLYCAPTCHAV1-PassedAlways}

{!FRIENDLYCAPTCHAV1-PassedAlways}
   <p>Prüfung fehlgeschlagen, Code ~FRIENDLYCAPTCHAV1-LastResponseCode~</p>

   {FRIENDLYCAPTCHAV1-LastPlainResponse}
      <pre>~FRIENDLYCAPTCHAV1-LastPlainResponse~</pre>
   {/FRIENDLYCAPTCHAV1-LastPlainResponse}
{/!FRIENDLYCAPTCHAV1-PassedAlways}
```

> [!WARNING]
>
> Beide Tags müssen im Template hinter `PassedOnce` oder `PassedAlways` stehen. Erst diese Klammerungen führen die Prüfung durch und setzen dabei Code und Antwort. Davor liefert der Code den Wert 0, was fälschlich nach einer bestandenen Prüfung aussieht.
>
> `LastPlainResponse` gibt die Antwort des Dienstes unverändert aus. Sie gehört in eine Testumgebung, nicht auf eine Seite, die Besucher sehen. Klammern Sie die Ausgabe zumindest so, dass sie nur im Testmodus erscheint.

### Die Statuscodes

| Code | Bedeutung |
| - | - |
| 0 | bestanden |
| 1 | in diesem Seitenaufruf bereits geprüft, nicht bestanden |
| 2 | in dieser Sitzung bereits geprüft, nicht bestanden |
| 3 | der Friendly-Captcha-Dienst hat die Lösung abgelehnt |
| 200 | es wurde keine Lösung mitgeschickt, das Feld `frc-captcha-solution` fehlt oder ist leer |
| 201 | in der Shopkonfiguration fehlt die Prüfadresse |
| 202 | in der Shopkonfiguration fehlt der API-Schlüssel |
| 300 | die Verbindung zum Dienst kam nicht zustande |
| 301 | der Dienst hat keine Antwort geliefert |
| 302 | die Antwort des Dienstes war kein auswertbares JSON |
| 400 | interner Fehler beim Aufbau der Anfrage |
| 9000 plus HTTP-Status | der Dienst hat mit einem anderen Status als 200 geantwortet, beispielsweise 9403 oder 9500 |

Die Codes 1 und 2 sind keine Fehler des Besuchers. Sie besagen, dass für diesen Seitenaufruf beziehungsweise diese Sitzung bereits ein negatives Ergebnis vorliegt und deshalb nicht erneut angefragt wurde.

Die Codes 201 und 202 zeigen auf die Shopkonfiguration, nicht auf das Template. Treten sie auf, ist Friendly Captcha im Shop nicht vollständig eingerichtet.

## Die Tags im Überblick

| Tag | Einzel-Tag | Bereichs-Tag | negatives Bereichs-Tag | Schleifen-Tag |
| - | - | - | - | - |
| `FRIENDLYCAPTCHAV1-ApplicationID` | ja | ja | ja | – |
| `FRIENDLYCAPTCHAV1-APIUrl` | ja | ja | ja | – |
| `FRIENDLYCAPTCHAV1-PassedOnce` | – | ja | ja | – |
| `FRIENDLYCAPTCHAV1-PassedAlways` | – | ja | ja | – |
| `FRIENDLYCAPTCHAV1-LastPlainResponse` | ja | ja | ja | – |
| `FRIENDLYCAPTCHAV1-LastResponseCode` | ja | – | – | – |

Alle Tags sind auf allen Templates zulässig. Die Schreibweise des Tagnamens spielt keine Rolle.

## Verwandte Themen

* Wegweiser: Spamschutz für Formulare
* Referenz: [RECAPTCHAV3- (reCAPTCHA v3)](https://dokumentation.websale.de/v8s/referenz/tags/recaptchav3-google-recaptcha.md)
* Referenz: [FORM- (Formulare)](https://dokumentation.websale.de/v8s/referenz/tags/form-formulare.md)


## Related topics

- [RECAPTCHAV3- (Google reCAPTCHA)](https://dokumentation.websale.de/v8s/referenz/tags/recaptchav3-google-recaptcha.md)
- [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)
- [security - Sicherheitsregeln](https://dokumentation.websale.de/konfiguration/security-sicherheitsregeln.md)
- [Konfigurations-Deeplinks](https://dokumentation.websale.de/admin-interface/konfigurations-deeplinks.md)


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