RECAPTCHAV3- (Google reCAPTCHA) - WEBSALE Dokumentation

Google reCAPTCHA V3 does not give the visitor a task, but observes their behavior and assigns a score between 0 and 1. The shop retrieves this score from Google and uses a configured threshold to decide whether it considers the visitor to be a human. In the template, this happens in three steps: you load the script from Google, pass the token generated by Google to the shop, and then query the result. The six RECAPTCHAV3- tags cover exactly these three steps. Guide: Captcha protection

All tags on this page are permitted in all templates.

Friendly Captcha is the second provider available in the shop system. The tags there have different names but work according to exactly the same pattern.

Reference: FRIENDLYCAPTCHAV1- (Friendly Captcha)

Loading the script from Google

Two tags return the details that the script needs.

Tag	Returns
`RECAPTCHAV3-APIUrl`	the configured address of the reCAPTCHA interface
`RECAPTCHAV3-SiteKey`	the configured site key

<script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>

Both values come from the shop configuration. Do not hard-code them in the template; otherwise, the integration breaks as soon as the key is changed or a subshop uses its own.

The previous documentation lists both tags only as single tags. In the shop system, they also apply as range tags, specifically when the respective value is configured. This lets you cleanly hide the entire integration if reCAPTCHA is not set up for this shop.

{RECAPTCHAV3-SiteKey}
   <script src="~RECAPTCHAV3-APIUrl~?render=~RECAPTCHAV3-SiteKey~"></script>
{/RECAPTCHAV3-SiteKey}

Passing the token to the shop

Google generates a token in the browser. Your form must send this token to the shop under the name ws_recaptchav3_token; otherwise, the shop cannot check anything.

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

The field name ws_recaptchav3_token is fixed and has no tag of its own. Write it exactly like this. A missing or empty token results in response code 200; the check is then considered failed.

A token from Google is short-lived. Therefore, only get it immediately before submitting, not when the page is built, if a lot of time can pass between building and submitting.

Querying the result

Two ranges query the result. The difference lies in how often the check is performed.

Tag	Checks
`RECAPTCHAV3-PassedAlways`	again on every page call
`RECAPTCHAV3-PassedOnce`	once per session; after that, the stored result applies

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

Neither tag is a passive query. When evaluating them, the shop system sends a request to Google and waits for the response. Therefore, only place them where the result is needed, and not as a precaution on every page. Every check actually performed is counted in the shop system.

Once RECAPTCHAV3-PassedOnce has stored a negative result in the session, it continues to return “failed” for the rest of the session and does not ask Google again. The visitor cannot get out of this state on their own. At the point where they should try again, additionally use RECAPTCHAV3-PassedAlways. A successful check achieved with it cancels the stored negative result.

RECAPTCHAV3-PassedAlways checks exactly once per page call. Placing it several times on the same page therefore does not generate a second request but reuses the result of the first tag.

The check is passed if the score returned by Google is greater than the configured minimum value. A score that exactly equals the minimum value is considered failed.

If Google cannot be reached, both tags report “failed”. A tolerance for technical faults stored in the configuration does not apply here. Therefore, for important functions, plan a path that continues even without a successful check.

In the cross-references of both pages, the previous documentation misspells the tag name as RECHAPTAV3-PassedOnce and RECHAPTAV3-PassedAlways, respectively. The correct prefix is RECAPTCHAV3-.

Tracing errors

After a check, two tags are available for troubleshooting.

Tag	Returns
`RECAPTCHAV3-LastResponseCode`	the technical status code of the last check
`RECAPTCHAV3-LastPlainResponse`	the unchanged response from Google

{RECAPTCHAV3-PassedAlways}
   Prüfung bestanden.
{/RECAPTCHAV3-PassedAlways}

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

Both tags refer to the last check. They must therefore be placed in the template after RECAPTCHAV3-PassedOnce or RECAPTCHAV3-PassedAlways. Before that, no check has taken place yet, and the code is 0, which mistakenly looks like a passed test.

The response codes

The previous documentation only states “0 means passed, everything else means failed”. The shop system additionally distinguishes what caused the result.

Code	Meaning
0	check passed
1	already checked and failed in this page call
2	already checked and failed in this session
3	Google responded, the score is not sufficient
200	no token passed, the `ws_recaptchav3_token` field is missing or empty
201	the verification address is missing in the configuration
202	the secret key is missing in the configuration
300	the request to Google failed
301	Google returned nothing
302	the response from Google could not be evaluated
400	the shop system could not prepare the request

Codes 1 and 2 do not mean that a check was just performed. They indicate that an earlier negative result was reused. Code 2 only comes from RECAPTCHAV3-PassedOnce, code 1 only from RECAPTCHAV3-PassedAlways on a second occurrence on the same page.

Codes 201 and 202 indicate an incomplete shop configuration, not a behavior of the visitor.

RECAPTCHAV3-LastPlainResponse returns Google’s response as JSON, unchanged. Among other things, it contains the score and the action name. For further processing in the template, pass the content to the JSON interface.

Reference: EJD- (JSON interface)

Do not output RECAPTCHAV3-LastPlainResponse on a publicly visible page. The response contains technical details about the shop that are nobody’s business but yours. A separate, protected page is suitable for troubleshooting.

The tags at a glance

Tag	Single tag	Range tag	Negative range tag	Loop tag
`RECAPTCHAV3-APIUrl`	yes	yes	yes	–
`RECAPTCHAV3-SiteKey`	yes	yes	yes	–
`RECAPTCHAV3-PassedOnce`	–	yes	yes	–
`RECAPTCHAV3-PassedAlways`	–	yes	yes	–
`RECAPTCHAV3-LastPlainResponse`	yes	yes	yes	–
`RECAPTCHAV3-LastResponseCode`	yes	–	–	–

All six tags are permitted in all templates. As a range tag, RECAPTCHAV3-LastResponseCode is treated as an invalid tag.

Guide: Captcha protection
Reference: FRIENDLYCAPTCHAV1- (Friendly Captcha)
Reference: EJD- (JSON interface)
Reference: Captcha section in the shop configuration

​Loading the script from Google

​Passing the token to the shop

​Querying the result

​Tracing errors

​The response codes

​The tags at a glance

​Related topics

Loading the script from Google

Passing the token to the shop

Querying the result

Tracing errors

The response codes

The tags at a glance

Related topics