Aller au contenu

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 :

Fenêtre de terminal
npm install altcha

Importer dans votre projet :

form.js
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 :

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

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

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

Configuration

Options requises (au moins une est obligatoire) :

  • challengeurl - URL de votre serveur pour obtenir le challenge. Référez-vous à l’intégration du serveur.
  • challengejson - Données de challenge codées en JSON. Si vous évitez une requête HTTP à challengeurl, fournissez les données ici.

Options supplémentaires :

  • auto - Vérifier automatiquement sans interaction de l’utilisateur (valeurs possibles : onfocus, onload, onsubmit).
  • blockspam - Utilisé uniquement en conjonction avec l’option spamfilter. S’il est activé, il bloquera l’envoi du formulaire et échouera la vérification si le filtre anti-spam renvoie une classification négative. Cela empêche effectivement l’envoi du formulaire.
  • delay - Le délai artificiel en millisecondes à appliquer avant la vérification (par défaut à 0).
  • expire - L’expiration du défi (durée en millisecondes).
  • floating - Activer Floating UI (valeurs possibles : auto, top, bottom).
  • floatinganchor - Le sélecteur CSS de “l’ancre” à laquelle l’interface utilisateur flottante sera attachée (par défaut le button[type="submit"] dans le formulaire concerné).
  • hidefooter - Masquer le pied de page (lien ALTCHA).
  • hidelogo - Masquer le logo ALTCHA.
  • maxnumber - Le nombre maximal pour itérer jusqu’à (par défaut à 1 000 000).
  • name - Le nom du champ caché contenant la charge utile (par défaut à “altcha”).
  • refetchonexpire - Récupère et valide automatiquement à nouveau lorsque le défi expire (défini sur true par défaut).
  • spamfilter - Activez la fonction de Filtre Anti-Spam.
  • strings - Traduction des chaînes codées en JSON. Référez-vous à personnalisation.
  • verifyurl - Active la vérification côté serveur en configurant l’URL à utiliser pour les requêtes de vérification. Cette option peut être utilisée conjointement avec spamfilter pour activer la vérification côté serveur.
  • workers - Le nombre de travailleurs à utiliser pour PoW (par défaut à navigator.hardwareConcurrency || 8).
  • workerurl - L’URL du script du Worker (par défaut ./worker.js, fonctionne uniquement avec la version external).

Options de développement / test :

  • debug - Afficher les messages journaux dans la console.
  • mockerror - Fait échouer la vérification avec une erreur “mock”.
  • test - Génère un challenge “mock” dans le widget, contournant la requête à challengeurl.

Événements :

  • serververification - Se déclenche lors de la vérification côté serveur lors de l’utilisation de l’API.
  • statechange - Se déclenche chaque fois qu’un state interne change.
  • verified - Se déclenche lorsque le challenge est vérifié.

Utilisation des événements :

form.js
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 bundle de distribution par défaut de WebComponent inclut les styles et le worker dans un seul fichier. Cela peut poser des problèmes avec des règles CSP strictes. Si vous avez besoin de respecter strictement la CSP, envisagez d’utiliser les scripts situés dans le répertoire /dist_external ou importez la version external:

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