Salta ai contenuti
ALTCHA ALTCHA ALTCHA

Integrazione del Sito Web

L’integrazione di ALTCHA nel tuo sito web o web app è semplice e può essere fatta in pochi minuti.

Il metodo più semplice è quello di utilizzare il nostro widget Web Component (controlla la demo sulla pagina principale).

Installazione tramite NPM

Installa il pacchetto:

Terminal window
npm install altcha

Importalo nel tuo progetto:

form.js
import 'altcha';

In alternativa, scarica lo script

Scarica lo script ALTCHA da GitHub o utilizza il CDN:

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

o jsdelivr.net:

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

Per integrare il widget, aggiungi lo script al tuo sito web:

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

Per un’integrazione ottimale, posiziona il tag dello script all’interno della sezione <head>.

Utilizzo di <altcha-widget>

Il widget ALTCHA funziona come un Web Component e utilizza le capacità interne del browser per registrare un nuovo tag <altcha-widget>. Integra questo tag all’interno dei tuoi moduli:

form.html
<form>
  <altcha-widget
    challengeurl="{IL TUO_SERVER_QUI}"
  ></altcha-widget>
</form>

Configura challengeurl con l’indirizzo del tuo server, oppure utilizza l’API ufficiale per un’integrazione più semplice e veloce.

Configurazione

Opzioni richieste (almeno una è richiesta):

  • challengeurl - URL del tuo server per recuperare la sfida. Fai riferimento all’integrazione del server.
  • challengejson - Dati della sfida in formato JSON. Se si desidera evitare una richiesta HTTP a challengeurl, fornire i dati qui.

Opzioni aggiuntive:

  • auto - Verifica automatica senza interazione dell’utente (valori possibili: onfocus, onload, onsubmit).
  • blockspam - Viene utilizzato solo in combinazione con l’opzione spamfilter. Se abilitato, bloccherà l’invio del modulo e farà fallire la verifica se il filtro antispam restituisce una classificazione negativa. Ciò impedisce effettivamente l’invio del modulo.
  • expire - Scadenza della sfida (durata in millisecondi).
  • hidefooter - Nascondi il piè di pagina (link di ALTCHA).
  • hidelogo - Nascondi il logo di ALTCHA.
  • maxnumber - Il numero massimo di iterazioni (impostato di default su 1.000.000).
  • name - Il nome del campo nascosto che contiene il payload (impostato di default su “altcha”).
  • refetchonexpire - Recupera e convalida automaticamente quando la sfida scade (impostazione predefinita true).
  • spamfilter - Abilita la funzione del Filtro Antispam.
  • strings - Stringhe di traduzione codificate in JSON. Fai riferimento alla personalizzazione.
  • verifyurl - Abilita la verifica lato server configurando l’URL da usare per le richieste di verifica. Questa opzione può essere usata insieme a spamfilter per abilitare la verifica lato server.
  • workers - Il numero di workers da utilizzare per PoW (impostato su navigator.hardwareConcurrency || 8).

Opzioni di sviluppo/test:

  • debug - Stampa messaggi di log nella console.
  • mockerror - Fa fallire sempre la verifica con un errore “mock”.
  • test - Genera una sfida “mock” nel widget, bypassando la richiesta a challengeurl.

Eventi:

  • serververification - Si attiva durante la verifica lato server quando si utilizza l’API.
  • statechange - Sfruttato ogni volta che uno stato interno cambia.
  • verified - Attivato quando la sfida è verificata.

Utilizzo degli eventi:

form.js
document.querySelector('#altcha').addEventListener('statechange', (ev) => {
  // lo stato può essere: unverified, verifying, verificato, errore
  console.log('stato:', ev.detail.state);
  if (ev.detail.state === 'verified') {
    // il payload contiene dati codificati in base64 per il server
    console.log('payload:', ev.detail.payload);
  }
});

Avvertenze

  • Requisito di contesto sicuro

    Il widget utilizza l’interfaccia subtle.crypto integrata del browser per calcolare soluzioni in modo sicuro. È essenziale notare che questa interfaccia crittografica è disponibile esclusivamente in un contesto sicuro, comunemente implementato tramite HTTPS.

    Il widget richiede una connessione HTTPS sicura per funzionare. I siti web serviti tramite connessioni HTTP non sicure non supporteranno la funzionalità del widget a causa dell’assenza dell’interfaccia crittografica richiesta. Per garantire un’operatività senza problemi del widget, servire sempre il tuo sito web in modo sicuro tramite HTTPS.

  • Dipendenza da JavaScript

    Il widget funziona con JavaScript e dipende dall’ambiente di esecuzione di quest’ultimo per eseguire funzioni di computazione e invio. Di conseguenza, i browser abilitati a JavaScript sono un requisito fondamentale affinché gli utenti interagiscano con successo con il widget.

    Quando integrati il widget nei moduli del sito web, considera che gli utenti senza JavaScript abilitato nei loro browser non saranno in grado di utilizzare o inviare moduli protetti dal widget. Assicurati che il tuo pubblico sia consapevole di questo requisito per una presentazione senza problemi dei moduli.