Salta ai contenuti
ALTCHA ALTCHA ALTCHA

Risoluzione dei problemi

Questa pagina fornisce indicazioni per risolvere problemi comuni relativi alle integrazioni di ALTCHA. Per iniziare, abilita la modalità debug sul widget e controlla i log nella console dello sviluppatore.

Modalità Debug

Per abilitare la modalità debug sul widget, utilizza l’attributo debug:

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

La modalità debug mostrerà i messaggi di log sulla console. Apri la console dello sviluppatore del tuo browser per visualizzare questi log.

Problemi Comuni

Widget Non Trova la Soluzione

Problema:

Il widget segnala “Verifica fallita” e sulla console appare “Impossibile trovare una soluzione” (con debug abilitato).

Soluzione:

Questo problema potrebbe verificarsi a causa di:

  1. Numero Casuale Superiore al Massimo: Assicurati che il numero casuale generato dal tuo server non superi il numero massimo configurato. Per impostazione predefinita, il numero massimo è 1.000.000, ma può essere sovrascritto dal parametro maxnumber nella risposta della sfida. Allinea la generazione di numeri casuali del tuo server con questo massimo.

  2. Calcolo Sfida Errato: Verifica l’implementazione del tuo server. Per dettagli, consulta la documentazione del server o le librerie ufficiali per implementazioni specifiche del linguaggio. Ad esempio, controlla se salt=some_salt?expires=1722614680 e number=1234 generano una challenge SHA-256 uguale a 8b1fa4ee51e9e9c8b53cd0c080ca42458accc39424a13fb51e56cfe439814d5f. Assicurati che eventuali parametri aggiuntivi (ad es. expires) siano inclusi nell’input hash.

Secure Context

Problema:
Il widget ALTCHA non funziona e mostra il seguente errore nella console sviluppatori:
Uncaught TypeError: Cannot read properties of undefined (reading 'digest').

Soluzione:
Il widget ALTCHA utilizza l’interfaccia SubtleCrypto integrata nel browser per eseguire operazioni crittografiche in modo sicuro. Questa interfaccia è disponibile solo in un contesto sicuro, che generalmente richiede HTTPS o configurazioni specifiche di localhost.

Per risolvere questo problema:

  1. Assicurati di accedere al tuo sito Web tramite HTTPS.
  2. Per lo sviluppo locale, utilizza domini localhost supportati, come:
    • http://localhost
    • http://*.localhost (ad esempio, http://miapp.localhost)

Questo abiliterà il contesto sicuro necessario per il corretto funzionamento del widget.

I listener degli eventi non funzionano

Problema:

Eventi come statechange o verified non vengono attivati.

Soluzione:

Assicurati di aggiungere i listener degli eventi solo dopo che lo script ALTCHA è stato caricato e il componente inizializzato.

  1. Aggiungere i listener dopo l’inizializzazione:
    I listener degli eventi devono essere aggiunti solo dopo che lo script ALTCHA è stato completamente caricato e il componente inizializzato.

    • Per framework moderni e bundler:
      Assicurati di importare import 'altcha' nella tua applicazione.

    • Per JavaScript personalizzato:
      Utilizza l’evento DOMContentLoaded per aggiungere i listener:

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

  2. Gestire gli import asincroni:
    Se utilizzi importazioni asincrone come import('altcha'), attendi che l’importazione venga risolta prima di aggiungere i listener:

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

Problemi con il rendering lato server (SSR)

Problema:

Quando si utilizzano framework come Next.js o SvelteKit, la build può fallire con l’errore ReferenceError: customElements is not defined.

Soluzione:

Il widget ALTCHA è un WebComponent personalizzato che dipende dalla proprietà Window.customElements, che di solito non è disponibile negli ambienti SSR.

Per risolvere questo problema, assicurati che il widget venga importato solo sul client (browser). Ad esempio, usa la funzione dinamica import('altcha'). Alcuni framework offrono funzioni di supporto per rilevare se il codice viene eseguito sul server. In caso contrario, puoi verificare manualmente l’ambiente del browser controllando typeof window.

In SvelteKit, puoi usare $app/environment per rilevare se il codice viene eseguito nel browser:

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


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


<altcha-widget></altcha-widget>

Problemi di Politica di Sicurezza dei Contenuti (CSP)

Problema:

Il widget non si visualizza correttamente oppure sulla console compaiono errori relativi a CSP.

Soluzione:

Consulta la documentazione sulla Politica di Sicurezza dei Contenuti (CSP) per configurare correttamente il CSP per il widget.

Problemi di Scambio di Risorse con Origine Diversa (CORS)

Problema:

Il widget non riesce a recuperare la sfida dal server e compaiono errori correlati a CORS sulla console.

Soluzione:

Questo problema sorge quando il tuo sito web o applicazione si trova su un dominio diverso rispetto al tuo server. Abilita il CORS (Cross-Origin Resource Sharing) sul tuo server. Una configurazione CORS di base include:

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

Per una guida dettagliata, consulta la documentazione di MDN.