Plugins

A partir da versão 0.9.x, o widget ALTCHA suporta uma variedade de plugins que estendem sua funcionalidade principal. Os plugins permitem adicionar facilmente recursos como análises, obfuscação de dados e uploads de arquivos sem modificar o código principal.

Os plugins disponíveis incluem:

• Analytics
• Obfuscation
• Upload

Habilitando Plugins

Para habilitar um plugin, basta importar o script do plugin do pacote altcha:

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

Alternativamente, você pode incluir os scripts através da tag <script>, usando arquivos do diretório dist_plugins ou um 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>

Recomenda-se importar os plugins antes do pacote principal altcha para garantir que sejam registrados antes da criação de quaisquer instâncias de widgets.

Analytics Plugin

O plugin de Analytics permite rastrear interações de formulários usando os Formulários ALTCHA. É fácil de habilitar e não requer configuração adicional:

import 'altcha/analytics';

Para mais detalhes, consulte a documentação de envio HTML.

Obfuscation Plugin

O plugin de Obfuscation é projetado para proteger dados sensíveis, como endereços de e-mail e números de telefone, tornando-os difíceis de serem rastreados por bots:

import 'altcha/obfuscation';

Após habilitar este plugin, configure o atributo obfuscated no seu widget conforme descrito na documentação de obfuscação de dados.

Upload Plugin

O plugin de Upload facilita uploads de arquivos a partir de entradas type=file em formulários HTML personalizados, integrando-se perfeitamente com os Formulários ALTCHA. Ele suporta uploads automáticos e criptografia de ponta a ponta (E2E) para arquivos:

import 'altcha/upload';

Para mais informações, consulte a documentação de envio HTML.

Uso Avançado

Acesso Direto

O widget ALTCHA exporta uma função getPlugin(name), que retorna uma instância do plugin especificado. Isso permite interagir diretamente com o plugin. Por exemplo, para adicionar um arquivo usando o plugin de Upload:

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

Criando Plugins Personalizados

Se você precisar de funcionalidades além do que os plugins integrados oferecem, você pode criar seu próprio plugin. Aqui está um exemplo mínimo de como estruturar um plugin personalizado:

class MyPlugin {
  static pluginName = 'myplugin';

  constructor(context) {
    // Código de inicialização para o seu plugin
  }

  destroy() {
    // Código de limpeza quando o plugin é destruído
  }
}

// Registre seu plugin globalmente
if (typeof globalThis.altchaPlugins !== 'object') {
  globalThis.altchaPlugins = [];
}
globalThis.altchaPlugins.push(MyPlugin);

O construtor do plugin recebe um argumento context contendo o el (elemento HTML do widget) e outros métodos úteis.

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