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

> Embed the Friendly Captcha widget in the template, trigger the check and evaluate the result. With the complete list of status codes.

Friendly Captcha protects forms against automated abuse without giving the visitor a task. The browser solves a computational puzzle in the background and places the solution in a hidden field of the form. On submission, WEBSALE V8s verifies this solution with the Friendly Captcha service.

In the template, you need three things for this: the widget that generates the solution, triggering the check, and evaluating the result. There are tags for each of these steps.

The access data and addresses of the service are in the shop configuration. Of the four stored values, only two are output by tags, namely the public ones. The API key and the verification address remain server-side and deliberately have no tag.

Guide: Spam protection for forms · Reference: Shop configuration shop.config

## Embedding the widget

Two single tags return the values that the Friendly Captcha script needs in the browser.

| Tag | Returns |
| - | - |
| `FRIENDLYCAPTCHAV1-ApplicationID` | the stored ApplicationID, the sitekey in the widget |
| `FRIENDLYCAPTCHAV1-APIUrl` | the stored address of the 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]
>
> The widget belongs inside the `form` element. It writes its solution into a hidden field named `frc-captcha-solution`, and this is exactly the field WEBSALE V8s reads on submission. If the widget is outside the form, the field is not sent and the check fails with code 200.

> [!NOTE]
>
> Both tags also work as area tags. They apply if the respective value is stored in the shop configuration. This way, you only show the widget where Friendly Captcha is actually set up:
>
> ```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}
> ```

## Triggering the check

Two area tags trigger the check and show their area if it was passed.

| Tag | Checks |
| - | - |
| `FRIENDLYCAPTCHAV1-PassedOnce` | once per session; a passed result then continues to apply |
| `FRIENDLYCAPTCHAV1-PassedAlways` | anew on every page request |

```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]
>
> These two tags do not query a result; they perform the check. Each of them triggers a request to the Friendly Captcha service when first evaluated on a page. Therefore, only use them where a submitted form actually needs to be evaluated, and not as a precaution in a page header.

> [!NOTE]
>
> Within a page request, a request is made at most once. Further evaluations of the same tag or its negative counterpart use the remembered result. You can therefore safely keep both the area and the counter-area in the template.

> [!WARNING]
>
> If the Friendly Captcha service cannot be reached, the check is considered failed. The `fail-open` setting that exists for the captcha check elsewhere in the shop system does not affect these two tags. A form that is secured solely by this area tag becomes unusable for everyone if the service is disrupted. Plan a recognisable notice in the counter-area for this.

### When to use which

`PassedOnce` is intended for cases in which a visitor fills out several protected forms within one session. They solve the puzzle once and are then considered verified. This is convenient, but only protects the first submission.

`PassedAlways` checks each submission individually. This is the choice for forms that can be abused individually, for example a contact form or an enquiry.

> [!WARNING]
>
> `PassedOnce` remembers not only the passed result but also the failed one, and does not query again afterwards. If the first check in a session failed, the tag returns code 2 for the rest of the session, no matter what the visitor enters afterwards. This also affects the harmless case where a form was submitted once without a solved puzzle.
>
> The only way back is via `PassedAlways`. This tag queries again and, if successful, also sets the session to passed. If you use `PassedOnce`, you should therefore secure repeated submission of the same form via `PassedAlways`.

## Evaluating the result

There are two further tags for troubleshooting.

| Tag | Returns |
| - | - |
| `FRIENDLYCAPTCHAV1-LastResponseCode` | the internal status code of the last check |
| `FRIENDLYCAPTCHAV1-LastPlainResponse` | the unchanged response of the Friendly Captcha service |

```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]
>
> Both tags must come after `PassedOnce` or `PassedAlways` in the template. Only these area tags perform the check and set the code and response in the process. Before that, the code returns the value 0, which falsely looks like a passed check.

> [!WARNING]
>
> `LastPlainResponse` outputs the service's response unchanged. It belongs in a test environment, not on a page that visitors see. At the very least, bracket the output so that it only appears in test mode.

### The status codes

| Code | Meaning |
| - | - |
| 0 | passed |
| 1 | already checked in this page request, not passed |
| 2 | already checked in this session, not passed |
| 3 | the Friendly Captcha service rejected the solution |
| 200 | no solution was sent; the field `frc-captcha-solution` is missing or empty |
| 201 | the verification address is missing in the shop configuration |
| 202 | the API key is missing in the shop configuration |
| 300 | the connection to the service could not be established |
| 301 | the service did not return a response |
| 302 | the service's response was not evaluable JSON |
| 400 | internal error while building the request |
| 9000 plus HTTP status | the service responded with a status other than 200, for example 9403 or 9500 |

> [!NOTE]
>
> Codes 1 and 2 are not errors by the visitor. They indicate that a negative result already exists for this page request or this session and that no new request was therefore made.

> [!NOTE]
>
> Codes 201 and 202 point to the shop configuration, not to the template. If they occur, Friendly Captcha is not fully set up in the shop.

## The tags at a glance

| Tag | Single tag | Area tag | Negative area tag | Loop tag |
| - | - | - | - | - |
| `FRIENDLYCAPTCHAV1-ApplicationID` | yes | yes | yes | – |
| `FRIENDLYCAPTCHAV1-APIUrl` | yes | yes | yes | – |
| `FRIENDLYCAPTCHAV1-PassedOnce` | – | yes | yes | – |
| `FRIENDLYCAPTCHAV1-PassedAlways` | – | yes | yes | – |
| `FRIENDLYCAPTCHAV1-LastPlainResponse` | yes | yes | yes | – |
| `FRIENDLYCAPTCHAV1-LastResponseCode` | yes | – | – | – |

All tags are permitted on all templates. The capitalisation of the tag name does not matter.

## Related topics

* Guide: Spam protection for forms
* Reference: RECAPTCHAV3- (reCAPTCHA v3)
* Reference: FORM- (forms)


## Related topics

- [RECAPTCHAV3- (Google reCAPTCHA)](https://dokumentation.websale.de/en/v8s/referenz/tags/recaptchav3-google-recaptcha.md)
- [External services and interfaces](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/externe-dienste-und-schnittstellen.md)
- [Validation and checking services](https://dokumentation.websale.de/en/konfiguration/validierungs-und-prufservices.md)
- [security - Security rules](https://dokumentation.websale.de/en/konfiguration/security-sicherheitsregeln.md)
- [Configuration deep links](https://dokumentation.websale.de/en/admin-interface/konfigurations-deeplinks.md)


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