RECAPTCHAV3- (Google reCAPTCHA) - WEBSALE Dokumentation

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

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

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

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

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

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

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

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.

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

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

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

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)

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.

​Das Skript von Google laden

​Den Token an den Shop übergeben

​Das Ergebnis abfragen

​Fehler nachvollziehen

​Die Antwortcodes

​Die Tags im Überblick

​Verwandte Themen

Das Skript von Google laden

Den Token an den Shop übergeben

Das Ergebnis abfragen

Fehler nachvollziehen

Die Antwortcodes

Die Tags im Überblick

Verwandte Themen