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:

npm install altcha

Importieren Sie es in Ihr Projekt:

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:

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

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

Beispiele

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

Bundle-Größe

Das Standard-Bundle von ALTCHA ist leichtgewichtig und kombiniert alle Assets, einschließlich CSS und den JavaScript-Web-Worker, in einer einzigen Datei. GZIP-komprimiert beträgt die Gesamtgröße nur 17 kB, wodurch das ALTCHA-Widget 94 % kleiner ist als reCAPTCHA.

Distribution	Größe (GZIP-komprimiert)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Konfiguration

Erforderliche Optionen (mindestens eine ist erforderlich):

challengeurl - URL Ihres Servers, von dem die Herausforderung abgerufen wird. Siehe Server-Integration.
challengejson - JSON-kodierte Herausforderungsdaten. Wenn eine HTTP-Anfrage an challengeurl vermieden werden soll, geben Sie die Daten hier an.

Zusätzliche Optionen:

auto: Automatische Verifizierung ohne Benutzereingriff (mögliche Werte: off, onfocus, onload, onsubmit).
delay: Künstliche Verzögerung in Millisekunden vor der Verifizierung (Standardwert: 0).
expire: Ablaufdauer der Herausforderung in Millisekunden.
floating: Aktivieren der schwebenden Benutzeroberfläche (mögliche Werte: auto, top, bottom).
floatinganchor: CSS-Selektor des “Ankers”, an den die schwebende Benutzeroberfläche angehängt wird (Standardwert: button[type="submit"] im zugehörigen Formular).
floatingoffset: Y-Versatz vom Ankerelement für die schwebende Benutzeroberfläche in Pixeln (Standardwert: 12).
hidefooter: Versteckt den Footer (ALTCHA-Link).
hidelogo: Versteckt das ALTCHA-Logo.
maxnumber: Höchstzahl für die Iteration (Standardwert: 1.000.000).
name: Name des versteckten Feldes, das die Nutzlast enthält (Standardwert: “altcha”).
strings: JSON-kodierte Übersetzungsstrings. Siehe Anpassung.
refetchonexpire: Automatisches erneutes Abrufen und erneute Verifizierung, wenn die Herausforderung abläuft (Standardwert: true).
workers: Anzahl der zu verwendenden Worker für PoW (Standardwert: navigator.hardwareConcurrency || 8, Maximalwert 16).
workerurl: URL des Worker-Skripts (Standardwert: ./worker.js, funktioniert nur mit external-Build).

Spamfilter-bezogene Optionen:

blockspam: Nur in Verbindung mit der Option spamfilter verwendet. Wenn aktiviert, wird die Formularübermittlung blockiert und die Verifizierung schlägt fehl, wenn der Spamfilter eine negative Klassifizierung zurückgibt. Dies verhindert die Formularübermittlung.
spamfilter: Aktiviert den Spamfilter.
verifyurl: URL für serverseitige Verifizierungsanfragen. Diese Option wird automatisch konfiguriert, wenn die Option spamfilter verwendet wird. Überschreiben Sie diese Einstellung nur, wenn Sie eine benutzerdefinierte Serverimplementierung verwenden.

Daten-Obfuskation-Optionen:

obfuscated: Die obfuskierten Daten als Base64-kodierte Zeichenfolge (erfordert das altcha/obfuscation-Plugin). Nur verwenden ohne challengeurl/challengejson.

Entwicklungs-/Testoptionen:

debug - Protokollnachrichten in der Konsole ausgeben.
mockerror - Verursacht, dass die Verifizierung immer mit einem “mock” Fehler fehlschlägt.
test - Generiert eine “mock” Herausforderung innerhalb des Widgets, wodurch die Anfrage an challengeurl umgangen wird.

Ereignisse

load - Wird ausgelöst, wenn das Widget geladen wird. Die exportierten Methoden sind nach diesem Ereignis verfügbar.
serververification - Wird während der serverseitigen Verifizierung ausgelöst, wenn die API verwendet wird.
statechange - Wird ausgelöst, wenn sich ein interner state ändert.
verified - Wird ausgelöst, wenn die Herausforderung verifiziert wurde.

Verwendung von Ereignissen:

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 des WebComponents enthält Styles und den Worker in einer einzigen Datei. Da der Web-Worker von einem Blob ausgeführt wird, müssen Sie die blob:-Quelle zu Ihrer CSP hinzufügen:

Content-Security-Policy: script-src 'self'; worker-src 'self' blob:

Das Bündeln aller Dateien in einer einzelnen Datei kann bei strengen CSP-Regeln Probleme verursachen. Für strenge CSP-Konformität sollten Sie die Skripte im Verzeichnis /dist_external verwenden oder den external-Build importieren:

import 'altcha/external/altcha.js';

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

altcha/external/altcha.js - Das WebComponent ohne eingebettete 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.