Zum Inhalt springen

Website Integration

Die Integration von ALTCHA in Ihre Website oder Webanwendung ist unkompliziert und kann innerhalb weniger Minuten durchgeführt werden.

Die einfachste Methode besteht darin, unser Webkomponenten-Widget zu verwenden (sehen Sie sich die Demo auf der Hauptseite an).

Installation über NPM

Installieren Sie das Paket:

Terminal-Fenster
npm install altcha

Importieren Sie es in Ihr Projekt:

form.js
import 'altcha';

Alternativ, laden Sie das Skript herunter

Laden Sie das ALTCHA-Skript von GitHub herunter oder verwenden Sie das CDN:

https://eu.altcha.org/js/latest/altcha.min.js

oder jsdelivr.net:

https://cdn.jsdelivr.net/npm/altcha/dist/altcha.min.js

Um das Widget zu integrieren, fügen Sie das Skript Ihrer Website hinzu:

form.html
<script async defer src="/altcha.js" type="module"></script>

Für eine optimale Integration platzieren Sie das Skript innerhalb des <head>-Abschnitts.

Verwendung von <altcha-widget>

Das ALTCHA-Widget fungiert als Webkomponente und nutzt die internen Fähigkeiten des Browsers, um ein neues Tag <altcha-widget> zu registrieren. Integrieren Sie dieses Tag in Ihre Formulare:

form.html
<form>
<altcha-widget
challengeurl="{HIER IHR SERVER}"
></altcha-widget>
</form>

Konfiguriere challengeurl mit der Adresse deines Servers oder nutze die offizielle API für eine einfachere und schnellere Integration.

Konfiguration

Erforderliche Optionen (mindestens eine ist erforderlich):

  • challengeurl - URL Ihres Servers, um die Herausforderung abzurufen. Siehe Serverintegration.
  • challengejson - JSON-kodierte Herausforderungsdaten. Wenn Sie eine HTTP-Anfrage an challengeurl vermeiden möchten, geben Sie die Daten hier ein.

Zusätzliche Optionen:

  • auto - Automatische Verifizierung ohne Benutzerinteraktion (mögliche Werte: onfocus, onload, onsubmit).
  • blockspam - Wird nur in Verbindung mit der Option spamfilter verwendet. Aktiviert blockiert es das Absenden des Formulars und das Bestehen der Verifizierung, wenn der Spam-Filter eine negative Klassifizierung zurückgibt. Dies verhindert effektiv das Absenden des Formulars.
  • delay - Die künstliche Verzögerung in Millisekunden, die vor der Verifizierung angewendet wird (Standardwert ist 0).
  • expire - Das Ablaufdatum der Herausforderung (Dauer in Millisekunden).
  • floating - Aktivieren Sie die Floating UI (mögliche Werte: auto, top, bottom).
  • floatinganchor - Der CSS-Selektor des „Ankers“, an den die schwebende Benutzeroberfläche angehängt wird (Standardwert ist der button[type="submit"] im zugehörigen Formular).
  • hidefooter - Versteckt den Footer (ALTCHA-Link).
  • hidelogo - Versteckt das ALTCHA-Logo.
  • maxnumber - Die maximale Anzahl, bis zu der iteriert wird (Standardwert: 1.000.000).
  • name - Der Name des versteckten Felds, das die Nutzlast enthält (Standardwert: “altcha”).
  • refetchonexpire - Lädt und validiert automatisch neu, wenn die Herausforderung abläuft (standardmäßig aktiviert).
  • spamfilter - Aktiviere die Spamfilter-Funktion.
  • strings - JSON-kodierte Übersetzungszeichenfolgen. Siehe Anpassung.
  • verifyurl - Aktiviert die Server-seitige Verifizierung durch Konfiguration der URL für Verifizierungsanfragen. Diese Option kann zusammen mit spamfilter verwendet werden, um die Server-seitige Verifizierung zu aktivieren.
  • workers - Die Anzahl der Worker, die für PoW genutzt werden (Standardwert: navigator.hardwareConcurrency || 8).
  • workerurl - Die URL des Worker-Skripts (Standard ist ./worker.js, funktioniert nur mit dem external-Build).

Entwicklungs- / Testoptionen:

  • debug - Gibt Lognachrichten in der Konsole aus.
  • mockerror - Verursacht, dass die Verifizierung immer mit einem “Mock”-Fehler fehlschlägt.
  • test - Generiert eine “Mock”-Herausforderung innerhalb des Widgets und umgeht die Anfrage an challengeurl.

Ereignisse:

  • serververification - Wird während der serverseitigen Verifikation bei Verwendung der API ausgelöst.
  • statechange - Wird ausgelöst, wenn sich der interne state ändert.
  • verified - Wird ausgelöst, wenn die Herausforderung verifiziert wird.

Verwendung von Ereignissen:

form.js
document.querySelector('#altcha').addEventListener('statechange', (ev) => {
// state kann sein: unverified, verifying, verified, error
console.log('state:', ev.detail.state);
if (ev.detail.state === 'verified') {
// payload enthält base64-kodierte Daten für den Server
console.log('payload:', ev.detail.payload);
}
});

Content Security Policy (CSP)

Das Standard-Distributionspaket der WebComponent enthält Stile und den Worker in einer einzigen Datei. Dies kann zu Problemen mit strengen CSP-Richtlinien führen. Wenn Sie eine strenge CSP-Konformität benötigen, verwenden Sie die Skripte im Verzeichnis /dist_external oder importieren Sie den external-Build:

form.js
import 'altcha/external/altcha.js';

Mit strenger CSP müssen Sie diese Teile separat einbinden:

  • altcha/external/altcha.js - Die WebComponent ohne eingebettetes CSS und WebWorker.
  • altcha/external/worker.js - Der WebWorker.
  • altcha/altcha.css - CSS für das Widget.

Einschränkungen

  • Erfordernis eines sicheren Kontextes

    Das Widget nutzt die eingebaute subtle.crypto-Schnittstelle des Browsers, um Lösungen sicher zu berechnen. Es ist wichtig zu beachten, dass diese kryptographische Schnittstelle ausschließlich in einem sicheren Kontext verfügbar ist, der in der Regel über HTTPS implementiert wird.

    Das Widget erfordert eine sichere HTTPS-Verbindung, um zu funktionieren. Websites, die über unsichere HTTP-Verbindungen bedient werden, unterstützen die Funktionalität des Widgets aufgrund des Fehlens der erforderlichen kryptographischen Schnittstelle nicht. Um einen reibungslosen Betrieb des Widgets zu gewährleisten, bedienen Sie Ihre Website immer sicher über HTTPS.

  • JavaScript-Abhängigkeit

    Das Widget funktioniert mit JavaScript und verlässt sich auf seine Ausführungsumgebung, um Berechnungs- und Übermittlungsfunktionen auszuführen. Folglich ist ein Browser mit aktiviertem JavaScript eine Voraussetzung dafür, dass Benutzer erfolgreich mit dem Widget interagieren können.

    Bei der Integration des Widgets in Website-Formulare sollten Sie bedenken, dass Benutzer ohne aktiviertes JavaScript in ihren Browsern nicht in der Lage sein werden, Formulare zu nutzen oder einzureichen, die durch das Widget geschützt sind. Stellen Sie sicher, dass Ihr Publikum sich dieser Anforderung bewusst ist, um eine reibungslose Formularübermittlung zu gewährleisten.