Zum Inhalt springen
ALTCHA ALTCHA ALTCHA

Fehlerbehebung

Diese Seite bietet Anleitungen zur Behebung von häufig auftretenden Problemen im Zusammenhang mit ALTCHA-Integrationen. Um zu beginnen, aktivieren Sie den Debug-Modus auf dem Widget und überprüfen Sie die Protokolle in der Entwicklerkonsole.

Debug-Modus

Um den Debug-Modus auf dem Widget zu aktivieren, verwenden Sie das Attribut debug:

<altcha-widget
  debug
></altcha-widget>

Der Debug-Modus gibt Protokollmeldungen auf der Konsole aus. Öffnen Sie die Entwicklerkonsole Ihres Browsers, um diese Protokolle anzuzeigen.

Häufige Probleme

Widget findet keine Lösung

Problem:

Das Widget meldet “Verifizierung fehlgeschlagen”, und die Konsole zeigt “Unable to find a solution” an (mit aktiviertem debug).

Lösung:

Dieses Problem kann auftreten aufgrund von:

  1. Zufallszahl überschreitet Maximum: Stellen Sie sicher, dass die Zufallszahl, die von Ihrem Server generiert wird, nicht das konfigurierte maximale Limit überschreitet. Standardmäßig beträgt die maximale Zahl 1.000.000, kann aber durch den Parameter maxnumber in der Challenge-Antwort überschrieben werden. Passen Sie die Zufallsgenerierung Ihres Servers an dieses Maximum an.

  2. Falsche Challenge-Berechnung: Überprüfen Sie die Implementierung auf Ihrem Server. Für weitere Details, siehe die Serverdokumentation oder offizielle Bibliotheken für sprachspezifische Implementierungen. Überprüfen Sie beispielsweise, ob salt=some_salt?expires=1722614680 und number=1234 einen SHA-256 challenge generieren, der gleich ist wie 8b1fa4ee51e9e9c8b53cd0c080ca42458accc39424a13fb51e56cfe439814d5f. Stellen Sie sicher, dass alle zusätzlichen Parameter (z.B. expires) in die Hash-Eingabe einbezogen werden.

Secure Context

Problem:
Das ALTCHA-Widget funktioniert nicht und zeigt folgende Fehlermeldung in der Entwicklerkonsole:
Uncaught TypeError: Cannot read properties of undefined (reading 'digest').

Lösung:
Das ALTCHA-Widget nutzt die eingebaute SubtleCrypto-Schnittstelle des Browsers für sichere kryptografische Operationen. Diese Schnittstelle ist nur in einem sicheren Kontext verfügbar, der in der Regel HTTPS oder bestimmte localhost-Konfigurationen erfordert.

Um dieses Problem zu beheben:

  1. Stellen Sie sicher, dass Ihre Website über HTTPS aufgerufen wird.
  2. Für die lokale Entwicklung nutzen Sie unterstützte localhost-Domains, wie:
    • http://localhost
    • http://*.localhost (z. B. http://meineapp.localhost)

Dadurch wird der sichere Kontext aktiviert, der für die Funktion des Widgets erforderlich ist.

Ereignis-Listener funktionieren nicht

Problem:

Ereignisse wie statechange oder verified werden nicht ausgelöst.

Lösung:

Stellen Sie sicher, dass Sie Ereignis-Listener erst anhängen, nachdem das ALTCHA-Skript geladen und die Komponente initialisiert wurde.

  1. Listener nach der Initialisierung anhängen:
    Ereignis-Listener müssen erst hinzugefügt werden, nachdem das ALTCHA-Skript vollständig geladen und die Komponente initialisiert wurde.

    • Für moderne Frameworks und Bundler:
      Stellen Sie sicher, dass Sie import 'altcha' in Ihre Anwendung einbinden.

    • Für benutzerdefiniertes JavaScript:
      Verwenden Sie das DOMContentLoaded-Ereignis, um Listener anzuhängen:

      document.addEventListener('DOMContentLoaded', () => {
        altchaWidgetElement.addEventListener('statechange', (event) => {
          // Handle statechange event
        });
      });

  2. Asynchrone Importe behandeln:
    Wenn Sie asynchrone Importe wie import('altcha') verwenden, warten Sie, bis der Import abgeschlossen ist, bevor Sie Listener hinzufügen:

    import('altcha').then(() => {
      altchaWidgetElement.addEventListener('statechange', (event) => {
        // Handle statechange event
      });
    });

Probleme mit Server-Side Rendering (SSR)

Problem:

Beim Einsatz von Frameworks wie Next.js oder SvelteKit kann der Build mit dem Fehler ReferenceError: customElements is not defined fehlschlagen.

Lösung:

Das ALTCHA-Widget ist ein benutzerdefiniertes WebComponent und hängt von der Window.customElements-Eigenschaft ab, die in SSR-Umgebungen normalerweise nicht verfügbar ist.

Um dieses Problem zu lösen, stellen Sie sicher, dass das Widget nur auf dem Client (Browser) importiert wird. Verwenden Sie beispielsweise die dynamische import('altcha')-Funktion. Einige Frameworks bieten Hilfsfunktionen an, um zu erkennen, ob der Code auf dem Server ausgeführt wird. Wenn nicht, können Sie manuell die Browser-Umgebung überprüfen, indem Sie typeof window abfragen.

In SvelteKit können Sie $app/environment verwenden, um zu erkennen, ob der Code im Browser ausgeführt wird:

+page.svelte
<script>
  import { browser } from '$app/environment';


  if (browser) {
    import('altcha');
  }
</script>


<altcha-widget></altcha-widget>

Probleme mit Content Security Policy (CSP)

Problem:

Das Widget wird nicht richtig gerendert oder die Konsole zeigt mit CSP verbundene Fehler an.

Lösung:

Konsultieren Sie die Content Security Policy-Dokumentation, um die CSP ordnungsgemäß für das Widget zu konfigurieren.

Probleme mit Cross-Origin Resource Sharing (CORS)

Problem:

Das Widget kann die Challenge nicht vom Server abrufen, und mit CORS verbundene Fehler erscheinen in der Konsole.

Lösung:

Dieses Problem tritt auf, wenn Ihre Website oder Anwendung sich auf einer anderen Domain als Ihr Server befindet. Aktivieren Sie CORS (Cross-Origin Resource Sharing) auf Ihrem Server. Eine grundlegende CORS-Konfiguration enthält:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, POST, OPTIONS

Für ausführliche Anleitungen, siehe die MDN-Dokumentation.