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:

npm install altcha

Importalo nel tuo progetto:

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:

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

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

Esempi

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

Dimensione del Bundle

Il bundle predefinito di ALTCHA è leggero, combinando tutte le risorse, inclusi CSS e il Web Worker JavaScript, in un unico file. GZIPpato, il totale è di soli 17 kB, rendendo il widget ALTCHA più piccolo del 94% rispetto a reCAPTCHA.

Distribuzione	Dimensione (GZIPpato)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Configurazione

Opzioni richieste (ne è richiesta almeno una):

challengeurl - URL del tuo server da cui recuperare la sfida. Consulta integrazione del server.
challengejson - Dati della sfida codificati in 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: off, onfocus, onload, onsubmit).
delay: Ritardo artificiale in millisecondi prima della verifica (valore predefinito: 0).
expire: Durata della scadenza della sfida in millisecondi.
floating: Abilita l’interfaccia utente flottante (valori possibili: auto, top, bottom).
floatinganchor: Selettore CSS dell‘“ancora” a cui sarà collegata l’interfaccia utente flottante (valore predefinito: button[type="submit"] nel modulo correlato).
floatingoffset: Offset Y dall’elemento di ancoraggio per l’interfaccia utente flottante in pixel (valore predefinito: 12).
hidefooter: Nasconde il footer (link ALTCHA).
hidelogo: Nasconde il logo ALTCHA.
maxnumber: Numero massimo da iterare (valore predefinito: 1.000.000).
name: Nome del campo nascosto che contiene il payload (valore predefinito: “altcha”).
strings: Stringhe di traduzione codificate in JSON. Consulta personalizzazione.
refetchonexpire: Recupera e convalida automaticamente quando la sfida scade (valore predefinito: true).
workers: Numero di worker da utilizzare per PoW (valore predefinito: navigator.hardwareConcurrency || 8, valore massimo 16).
workerurl: URL dello script del Worker (valore predefinito: ./worker.js, funziona solo con la build external).

Opzioni relative al filtro antispam:

blockspam: Usato solo con l’opzione spamfilter. Se abilitato, bloccherà l’invio del modulo e la verifica fallirà se il filtro antispam restituisce una classificazione negativa. Questo impedisce l’invio del modulo.
spamfilter: Abilita il filtro antispam.
verifyurl: URL per le richieste di verifica lato server. Questa opzione è configurata automaticamente quando viene utilizzata l’opzione spamfilter. Sovrascrivere questa impostazione solo se si utilizza una implementazione server personalizzata.

Opzioni di offuscamento dei dati:

obfuscated: I dati offuscati forniti come stringa codificata in base64 (richiede il plugin altcha/obfuscation). Da utilizzare solo senza challengeurl/challengejson.

Opzioni di sviluppo/test:

debug: Stampa i messaggi di log nella console.
mockerror: Causa il fallimento della verifica con un errore “mock”.
test: Genera una sfida “mock” all’interno del widget, bypassando la richiesta a challengeurl.

Eventi

load: Si attiva quando il widget viene caricato. I metodi esportati diventano disponibili dopo questo evento.
serververification: Si attiva durante la verifica lato server quando si utilizza l’API.
statechange: Si attiva ogni volta che cambia uno stato interno.
verified: Si attiva quando la sfida è verificata.

Utilizzo degli eventi:

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);
  }
});

Content-Security-Policy (CSP)

Il pacchetto di distribuzione predefinito del WebComponent include stili e worker in un unico file. Poiché il web worker viene eseguito da un Blob, è necessario aggiungere la fonte blob: alla tua CSP:

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

Agruppare tutto in un solo file potrebbe causare problemi con le regole CSP rigide. Per la conformità CSP rigida, considera di utilizzare gli script situati nella directory /dist_external o di importare il build external:

import 'altcha/external/altcha.js';

Con una CSP rigida, dovrai includere queste parti separatamente:

altcha/external/altcha.js - Il WebComponent senza CSS iniettato e WebWorker.
altcha/external/worker.js - Il WebWorker.
altcha/altcha.css - CSS per il Widget.

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.