Aller au contenu
ALTCHA ALTCHA ALTCHA

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.
  • expire - L’expiration du challenge (durée en millisecondes).
  • 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).

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

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.