Complementos

A partir de la versión 0.9.x, el widget ALTCHA admite una variedad de complementos que extienden su funcionalidad principal. Los complementos te permiten agregar fácilmente características como análisis, obfuscación de datos y cargas de archivos sin modificar el código principal.

Los complementos disponibles incluyen:

• Analytics
• Obfuscation
• Upload

Habilitar Complementos

Para habilitar un complemento, simplemente importa el script del complemento desde el paquete altcha:

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

Alternativamente, puedes incluir los scripts mediante una etiqueta <script>, utilizando archivos del directorio dist_plugins o 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>

Se recomienda importar los complementos antes del paquete principal de altcha para asegurarse de que se registren antes de que se creen instancias de widgets.

Analytics Plugin

El complemento de Análisis te permite realizar un seguimiento de las interacciones con formularios utilizando los Formularios ALTCHA. Es fácil de habilitar y no requiere configuración adicional:

import 'altcha/analytics';

Para más detalles, consulta la documentación de envíos HTML.

Obfuscation Plugin

El complemento de Obfuscación está diseñado para proteger datos sensibles, como direcciones de correo electrónico y números de teléfono, haciéndolos difíciles de rastrear para los robots:

import 'altcha/obfuscation';

Después de habilitar este complemento, configura el atributo obfuscated en tu widget como se describe en la documentación de obfuscación de datos.

Upload Plugin

El complemento de Carga facilita subir archivos desde entradas type=file en formularios HTML personalizados, integrándose perfectamente con los Formularios ALTCHA. Admite cargas automáticas y cifrado de extremo a extremo (E2E) para archivos:

import 'altcha/upload';

Para más información, consulta la documentación de envíos HTML.

Uso Avanzado

Acceso Directo

El widget ALTCHA exporta una función getPlugin(nombre), que devuelve una instancia del complemento especificado. Esto te permite interactuar directamente con el complemento. Por ejemplo, para agregar un archivo usando el complemento de Carga:

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

Crear Complementos Personalizados

Si necesitas funcionalidades más allá de las ofrecidas por los complementos integrados, puedes crear tu propio complemento. Aquí tienes un ejemplo mínimo de cómo estructurar un complemento personalizado:

class MyPlugin {
  static pluginName = 'myplugin';

  constructor(context) {
    // Código de inicialización para tu complemento
  }

  destroy() {
    // Código de limpieza cuando se destruye el complemento
  }
}

// Registra tu complemento globalmente
if (typeof globalThis.altchaPlugins !== 'object') {
  globalThis.altchaPlugins = [];
}
globalThis.altchaPlugins.push(MyPlugin);

El constructor del complemento recibe un argumento context que contiene el (el elemento HTML del widget) y otros métodos útiles.

interface PluginContext {
  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>;
}