Intégration de site Web

Intégrer ALTCHA dans votre site Web ou application Web est simple et peut être réalisé en quelques minutes.

La méthode la plus facile consiste à utiliser notre widget Composant Web (consultez la démonstration sur la page principale).

Installation via NPM

Installer le package :

npm install altcha

Importer dans votre projet :

import 'altcha';

Sinon, téléchargez le script

Téléchargez le script ALTCHA depuis GitHub ou utilisez le CDN :

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

ou jsdelivr.net :

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

Pour intégrer le widget, ajoutez le script à votre site Web :

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

Pour une intégration optimale, placez la balise de script dans la section <head>.

Exemples

Utilisation de `<altcha-widget>`

Le widget ALTCHA fonctionne comme un Composant Web et utilise les capacités internes du navigateur pour enregistrer une nouvelle balise <altcha-widget>. Intégrez cette balise dans vos formulaires :

<form>
  <altcha-widget
    challengeurl="{VOTRE_SERVEUR_ICI}"
  ></altcha-widget>
</form>

Configurez challengeurl avec l’adresse de votre serveur, ou utilisez l’API officielle pour une intégration plus facile et plus rapide.

Taille du Bundle

Le bundle par défaut d’ALTCHA est léger, combinant tous les assets, y compris le CSS et le Web Worker JavaScript, en un seul fichier. Une fois GZIPpé, il ne totalise que 17 kB, rendant le widget d’ALTCHA 94 % plus petit que reCAPTCHA.

Distribution	Taille (GZIPpé)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Configuration

Options requises (au moins une est requise) :

challengeurl - URL de votre serveur pour récupérer le défi. Voir intégration du serveur.
challengejson - Données du défi encodées en JSON. Pour éviter une requête HTTP à challengeurl, fournissez les données ici.

Options supplémentaires :

auto: Vérification automatique sans interaction de l’utilisateur (valeurs possibles : off, onfocus, onload, onsubmit).
delay: Délai artificiel en millisecondes avant la vérification (par défaut : 0).
expire: Durée d’expiration du défi en millisecondes.
floating: Activer l’interface utilisateur flottante (valeurs possibles : auto, top, bottom).
floatinganchor: Sélecteur CSS de l‘“ancre” à laquelle l’interface utilisateur flottante sera attachée (par défaut : button[type="submit"] dans le formulaire concerné).
floatingoffset: Décalage Y par rapport à l’élément d’ancrage pour l’interface utilisateur flottante en pixels (par défaut : 12).
hidefooter: Masquer le pied de page (lien ALTCHA).
hidelogo: Masquer le logo ALTCHA.
maxnumber: Nombre maximal pour l’itération (par défaut : 1 000 000).
name: Nom du champ masqué contenant la charge utile (par défaut : “altcha”).
strings: Chaînes de traduction encodées en JSON. Voir personnalisation.
refetchonexpire: Re-récupération et revalidation automatiques lorsque le défi expire (par défaut : true).
workers: Nombre de workers à utiliser pour PoW (par défaut : navigator.hardwareConcurrency || 8, valeur maximale : 16).
workerurl: URL du script Worker (par défaut : ./worker.js, fonctionne uniquement avec la version external).

Options liées au filtre anti-spam :

blockspam: Utilisé uniquement avec l’option spamfilter. S’il est activé, il bloquera la soumission du formulaire et échouera à la vérification si le filtre anti-spam renvoie une classification négative. Cela empêche la soumission du formulaire.
spamfilter: Activer le filtre anti-spam.
verifyurl: URL pour les demandes de vérification côté serveur. Cette option est configurée automatiquement lorsque l’option spamfilter est utilisée. Remplacez ce paramètre uniquement si vous utilisez une implémentation de serveur personnalisée.

Options d’obfuscation des données :

obfuscated: Les données obfusquées fournies sous forme de chaîne encodée en base64 (nécessite le plugin altcha/obfuscation). À utiliser uniquement sans challengeurl/challengejson.

Options de développement/test :

debug : Imprimer des messages de log dans la console.
mockerror : Provoque l’échec de la vérification avec une erreur “mock”.
test : Génère un défi “mock” au sein du widget, en évitant la requête à challengeurl.

Événements

load : Se déclenche lorsque le widget est chargé. Les méthodes exportées deviennent disponibles après cet événement.
serververification : Se déclenche lors de la vérification côté serveur en utilisant l’API.
statechange : Se déclenche à chaque changement d’état interne.
verified : Se déclenche lorsque le défi est vérifié.

Utilisation des événements :

document.querySelector('#altcha').addEventListener('statechange', (ev) => {
  // L'état peut être : non vérifié, vérification, vérifié, erreur
  console.log('état :', ev.detail.state);
  if (ev.detail.state === 'verified') {
    // La charge utile contient des données codées en base64 pour le serveur
    console.log('charge utile :', ev.detail.payload);
  }
});

Content-Security-Policy (CSP)

Le paquet de distribution par défaut du WebComponent inclut les styles et le worker dans un seul fichier. Comme le web worker est exécuté à partir d’un Blob, vous devez ajouter la source blob: à votre CSP :

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

Regrouper tout dans un seul fichier peut poser des problèmes avec des règles CSP strictes. Pour une conformité stricte avec la CSP, envisagez d’utiliser les scripts situés dans le répertoire /dist_external ou d’importer le build external :

import 'altcha/external/altcha.js';

Avec une CSP stricte, vous devrez inclure ces parties séparément :

altcha/external/altcha.js - Le WebComponent sans CSS injecté et WebWorker.
altcha/external/worker.js - Le WebWorker.
altcha/altcha.css - CSS pour le Widget.

Limitations

Exigence de contexte sécurisé

Le widget utilise l’interface subtle.crypto intégrée du navigateur pour calculer des solutions en toute sécurité. Il est essentiel de noter que cette interface cryptographique est exclusivement disponible dans un contexte sécurisé, généralement mis en œuvre via HTTPS.

Le widget nécessite une connexion HTTPS sécurisée pour fonctionner. Les sites Web servis via des connexions HTTP non sécurisées ne prendront pas en charge la fonctionnalité du widget en raison de l’absence de l’interface cryptographique requise. Pour garantir le bon fonctionnement du widget, servez toujours votre site Web de manière sécurisée via HTTPS.
Dépendance JavaScript

Le widget fonctionne avec JavaScript et dépend de son environnement d’exécution pour effectuer des fonctions de calcul et de soumission. Par conséquent, les navigateurs activés JavaScript sont une condition préalable pour que les utilisateurs interagissent avec succès avec le widget.

Lors de l’intégration du widget dans les formulaires de site Web, prenez en compte que les utilisateurs sans JavaScript activé dans leurs navigateurs ne pourront pas utiliser ou soumettre des formulaires protégés par le widget. Assurez-vous que votre public est conscient de cette exigence pour une soumission de formulaire sans heurts.