FRIENDLYCAPTCHAV1- (Friendly Captcha)

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

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

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.

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:

{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

{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}

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.

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.

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.

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

{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}

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.

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

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.

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.

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

​Embedding the widget

​Triggering the check

​When to use which

​Evaluating the result

​The status codes

​The tags at a glance

​Related topics

Embedding the widget

Triggering the check

When to use which

Evaluating the result

The status codes

The tags at a glance

Related topics