Plugins

À partir de la version 0.9.x, le widget ALTCHA prend en charge une variété d’extensions qui étendent sa fonctionnalité de base. Les extensions vous permettent d’ajouter facilement des fonctionnalités telles que l’analyse, l’obfuscation des données et les téléchargements de fichiers sans modifier le code source principal.

Les extensions disponibles comprennent :

• Analytics
• Obfuscation
• Upload

Activation des Extensions

Pour activer une extension, importez simplement le script de l’extension à partir du package altcha :

import 'altcha/obfuscation';
import 'altcha';

Alternativement, vous pouvez inclure les scripts via une balise <script>, en utilisant des fichiers du répertoire dist_plugins ou un CDN :

<script src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist_plugins/obfuscation.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/altcha-org/altcha@main/dist/altcha.min.js"></script>

Il est recommandé d’importer les extensions avant le package principal altcha pour garantir qu’elles sont enregistrées avant la création de toute instance de widget.

Analytics Plugin

L’extension d’Analyse vous permet de suivre les interactions avec les formulaires en utilisant les formulaires ALTCHA. Il est facile à activer et ne nécessite aucune configuration supplémentaire :

import 'altcha/analytics';

Pour plus de détails, consultez la documentation sur les soumissions HTML.

Obfuscation Plugin

L’extension d’Obfuscation est conçue pour protéger les données sensibles, telles que les adresses e-mail et les numéros de téléphone, en les rendant difficiles à scraper par les bots :

import 'altcha/obfuscation';

Après avoir activé cette extension, configurez l’attribut obfuscated sur votre widget comme décrit dans la documentation sur l’obfuscation des données.

Upload Plugin

L’extension de Téléchargement facilite les téléchargements de fichiers à partir des entrées type=file dans des formulaires HTML personnalisés, s’intégrant parfaitement avec les formulaires ALTCHA. Elle prend en charge les téléchargements automatiques et le chiffrement de bout en bout (E2E) pour les fichiers :

import 'altcha/upload';

Pour plus d’informations, consultez la documentation sur les soumissions HTML.

Utilisation Avancée

Accès Direct

Le widget ALTCHA exporte une fonction getPlugin(nom) qui renvoie une instance de l’extension spécifiée. Cela vous permet d’interagir directement avec l’extension. Par exemple, pour ajouter un fichier en utilisant l’extension de Téléchargement :

const uploadPlugin = document.querySelector('#altcha').getPlugin('upload');
uploadPlugin.addFile('attachment', file);

Création d’Extensions Personnalisées

Si vous avez besoin de fonctionnalités au-delà de ce que les extensions intégrées offrent, vous pouvez créer votre propre extension. Voici un exemple minimal de comment structurer une extension personnalisée :

class MyPlugin {
  static pluginName = 'myplugin';

  constructor(context) {
    // Code d'initialisation pour votre extension
  }

  destroy() {
    // Code de nettoyage lorsque l'extension est détruite
  }
}

// Enregistrez votre extension globalement
if (typeof globalThis.altchaPlugins !== 'object') {
  globalThis.altchaPlugins = [];
}
globalThis.altchaPlugins.push(MyPlugin);

Le constructeur de l’extension reçoit un argument context contenant l’élément HTML el du widget et d’autres méthodes utiles :

interface ContexteExtension {
  el: HTMLElement;
  clarify(): Promise<void>;
  dispatch(event: string, details?: unknown): void;
  getConfiguration(): Configure;
  getFloatingAnchor(): HTMLElement | null;
  getState(): State;
  log(...args: unknown[]): void;
  reset(state?: State, err?: string | null): void;
  solve(data: Challenge | Obfuscated): Promise<{
    data: Challenge | Obfuscated;
    solution: Solution | ClarifySolution | null;
  }>;
  setFloatingAnchor(el: HTMLElement): void;
  setState(state: State, err?: string | null): void;
  verify(): Promise<void>;
}