Plugins

Ab Version 0.9.x unterstützt das ALTCHA-Widget eine Vielzahl von Plugins, die seine Kernfunktionalität erweitern. Plugins ermöglichen es Ihnen, Funktionen wie Analysen, Datenverschleierung und Datei-Uploads hinzuzufügen, ohne den Kerncode zu ändern.

Die verfügbaren Plugins umfassen:

• Analytics
• Obfuscation
• Upload

Aktivieren von Plugins

Um ein Plugin zu aktivieren, importieren Sie einfach das Skript des Plugins aus dem altcha-Paket:

import 'altcha/obfuscation';
import 'altcha';

Alternativ können Sie die Skripte über ein <script>-Tag einbinden, indem Sie Dateien aus dem dist_plugins-Verzeichnis oder einem CDN verwenden:

<script src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist_plugins/obfuscation.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist/altcha.min.js"></script>

Es wird empfohlen, Plugins vor dem Hauptpaket altcha zu importieren, um sicherzustellen, dass sie registriert sind, bevor Widget-Instanzen erstellt werden.

Analytics Plugin

Das Analytics-Plugin ermöglicht es Ihnen, Formularinteraktionen mit ALTCHA-Formularen nachzuverfolgen. Es ist einfach zu aktivieren und erfordert keine zusätzliche Konfiguration:

import 'altcha/analytics';

Für weitere Details siehe die Dokumentation zu HTML-Einreichungen.

Obfuscation Plugin

Das Obfuscation-Plugin dient dazu, sensible Daten wie E-Mail-Adressen und Telefonnummern zu schützen, indem sie für Bots schwer erkennbar gemacht werden:

import 'altcha/obfuscation';

Nach der Aktivierung dieses Plugins konfigurieren Sie das obfuscated-Attribut auf Ihrem Widget gemäß der Dokumentation zur Datenverschleierung.

Upload Plugin

Das Upload-Plugin erleichtert Datei-Uploads von type=file-Eingaben in benutzerdefinierten HTML-Formularen und integriert sich nahtlos in ALTCHA-Formulare. Es unterstützt automatische Uploads und Ende-zu-Ende-Verschlüsselung (E2E) für Dateien:

import 'altcha/upload';

Für weitere Informationen siehe die Dokumentation zu HTML-Einreichungen.

Erweiterte Verwendung

Direkter Zugriff

Das ALTCHA-Widget exportiert eine getPlugin(name)-Funktion, die eine Instanz des angegebenen Plugins zurückgibt. Dadurch können Sie direkt mit dem Plugin interagieren. Zum Beispiel um eine Datei mit dem Upload-Plugin hinzuzufügen:

const uploadPlugin = document.querySelector('#altcha').getPlugin('upload');
uploadPlugin.addFile('attachment', file);

Erstellen von benutzerdefinierten Plugins

Wenn Sie Funktionen benötigen, die über das Angebot der integrierten Plugins hinausgehen, können Sie Ihr eigenes Plugin erstellen. Hier ist ein minimales Beispiel, wie Sie ein benutzerdefiniertes Plugin strukturieren:

class MyPlugin {
  static pluginName = 'myplugin';

  constructor(context) {
    // Initialisierungscode für Ihr Plugin
  }

  destroy() {
    // Bereinigungsscode, wenn das Plugin zerstört wird
  }
}

// Registrieren Sie Ihr Plugin global
if (typeof globalThis.altchaPlugins !== 'object') {
  globalThis.altchaPlugins = [];
}
globalThis.altchaPlugins.push(MyPlugin);

Der Plugin-Konstruktor erhält ein context-Argument, das das el (HTML-Element des Widgets) und andere hilfreiche Methoden enthält:

interface PluginContext {
  el: HTMLElement;
  clarify(): Promise<void>;
  dispatch(event: string, details?: unknown): void;
  getConfiguration(): Configure;
  getFloatingAnchor(): HTMLElement | null;
  getState(): State;
  log(...args: unknown[]): void;
  reset(state?: State, err?: string | null): void;
  solve(data: Challenge | Obfuscated): Promise<{
    data: Challenge | Obfuscated;
    solution: Solution | ClarifySolution | null;
  }>;
  setFloatingAnchor(el: HTMLElement): void;
  setState(state: State, err?: string | null): void;
  verify(): Promise<void>;
}