React

Das Paket @myrasec/eu-captcha stellt die Komponente EuCaptcha bereit. Die Komponente zeichnet das Widget im Formular und meldet das Token an Ihren Quelltext.

Voraussetzungen

Die folgenden Voraussetzungen sind erfüllt:

Voraussetzung	Wert
React	ab Version 18
Sitekey	Öffentlicher Sitekey aus der Ansicht Details
Serverseite	Endpunkt, der das Token prüft

Paket installieren

Installieren Sie das Paket:

npm i @myrasec/eu-captcha

Komponente einbinden

Binden Sie die Komponente in das zu schützende Formular ein:

import { EuCaptcha, isEuCaptchaDone } from "@myrasec/eu-captcha";

const captchaSitekey = "EUCAPTCHA_SITE_KEY";

export function ContactForm() {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>): void {
    e.preventDefault();
    if (!isEuCaptchaDone()) {
      // challenge not yet complete
      return;
    }
    // proceed with form submission
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* your fields */}
      <EuCaptcha sitekey={captchaSitekey} />
      <button type="submit">Submit</button>
    </form>
  );
}

Hinweis

Sie prüfen die Einbindung mit einem beliebigen erfundenen Sitekey. Zu einem unbekannten Sitekey läuft das CAPTCHA mit den Vorgabewerten und lässt jeden Besucher passieren. Die Prüfung über den Endpunkt /verify lehnt das Token eines unbekannten Sitekeys dagegen mit dem Fehlercode invalid-input-sitekey ab.

Eigenschaften

Die folgenden Eigenschaften stehen zur Verfügung:

Eigenschaft	Typ	Vorgabe	Wirkung
sitekey	string	—	Öffentlicher Sitekey. Der Wert ist erforderlich.
theme	string	"light"	Darstellung, Werte "light" und "dark".
width	number	330	Breite des Widgets in Pixeln.
height	number	100	Höhe des Widgets in Pixeln.
widgetId	string	—	Eigene Kennung des Widgets. Ohne Angabe erzeugt das Paket eine Kennung. Für euCaptcha.execute() ist der Wert erforderlich.
autostart	boolean	true	Startet die Challenge automatisch. Der Wert false verschiebt den Start auf den Aufruf euCaptcha.execute(widgetId).
onComplete	(token: string) => void	—	Wird mit dem Token aufgerufen, sobald die Challenge bestanden ist.
onExpired	() => void	—	Wird aufgerufen, wenn das Token abläuft. Ein Token läuft 60 Minuten nach der Lösung ab.
onError	() => void	—	Wird bei einem Netzwerk- oder Serverfehler aufgerufen.
scriptSrc	string	"https://cdn.eu-captcha.eu/verify.js"	Adresse, von der das Paket das Skript verify.js lädt, etwa für eine Test- oder Staging-Umgebung. Nur Nachrichten vom Ursprung dieser Adresse gelten als vertrauenswürdig. Der erste Ladevorgang legt die Adresse fest, eine spätere abweichende Adresse bleibt ohne Wirkung.

Beispiele für die Darstellung:

<EuCaptcha sitekey={captchaSitekey} theme="dark" />
<EuCaptcha sitekey={captchaSitekey} width={280} />
<EuCaptcha sitekey={captchaSitekey} height={60} />

Rückrufe verwenden

<EuCaptcha
  sitekey={captchaSitekey}
  onComplete={(token: string) => console.log("token:", token)}
  onExpired={() => console.log("token expired")}
  onError={() => console.log("challenge error")}
/>

Challenge verzögert starten

Setzen Sie autostart auf false und vergeben Sie eine Kennung:

<EuCaptcha
  sitekey={captchaSitekey}
  widgetId="my-captcha"
  autostart={false}
/>

<button onClick={() => (window as any).euCaptcha.execute("my-captcha")}>Verify</button>

Next.js

Die Komponente greift auf Schnittstellen des Browsers zu und läuft daher nur im Browser.

Im App Router setzen Sie 'use client' an den Anfang der Datei:

'use client';

import { EuCaptcha, isEuCaptchaDone } from "@myrasec/eu-captcha";

Im Pages Router laden Sie die Komponente über next/dynamic ohne serverseitige Darstellung:

import dynamic from "next/dynamic";
import { isEuCaptchaDone } from "@myrasec/eu-captcha";

const EuCaptcha = dynamic(
  () => import("@myrasec/eu-captcha").then((m) => m.EuCaptcha),
  { ssr: false }
);

Dasselbe Vorgehen gilt für Gatsby, da auch dort das Paket @myrasec/eu-captcha zum Einsatz kommt.

Paket ohne React verwenden

Achtung

Der Aufruf loadEuCaptcha() setzt die globale Variable euCaptchaNoAutoInit. Das Skript verify.js zeichnet Elemente mit der Klasse eu-captcha danach nicht mehr selbst.

Das Paket lässt sich auch ohne React verwenden. React bleibt dabei eine Abhängigkeit des Pakets.

Um das Paket ohne React zu verwenden, gehen Sie wie folgt vor:

• ► Laden Sie die Bestandteile asynchron:

import { loadEuCaptcha, isEuCaptchaDone } from "@myrasec/eu-captcha";

loadEuCaptcha();

• ► Fügen Sie das Element in das Formular ein:

<div class="eu-captcha" data-sitekey="EUCAPTCHA_SITE_KEY"></div>

• ➔ Das Skript verify.js ist geladen.

Die unterstützten Attribute sind unter HTML und JavaScript beschrieben.

Zustand abfragen

Prüfen Sie vor dem Absenden, ob die Challenge bestanden ist:

import { isEuCaptchaDone } from "@myrasec/eu-captcha";

function handleSubmit(e: React.FormEvent<HTMLFormElement>): void {
    e.preventDefault();

    if (!isEuCaptchaDone()) {
        // challenge not yet complete
        return;
    }
    // proceed with form submission
}

Alternativ warten Sie auf die Nachricht euCaptchaCompleted am Fenster:

function listenForCaptchaDone(msg: MessageEvent): void {
    if (msg.data.type === "euCaptchaCompleted") {
        // enable submit button, update state, etc.
    }
}

window.addEventListener("message", listenForCaptchaDone, false);

Achtung

Die Prüfung im Browser steuert nur die Bedienung. Prüfen Sie das Token in jedem Fall zusätzlich auf dem Server. Siehe Endpunkt /verify.

Vollständiges Beispiel

Siehe React und PHP.