Plugins

Starting with version 0.9.x, the ALTCHA widget supports a variety of plugins that extend its core functionality. Plugins allow you to easily add features like analytics, data obfuscation, and file uploads without modifying the core code.

The available plugins include:

• Analytics
• Obfuscation
• Upload

Enabling Plugins

To enable a plugin, simply import the plugin’s script from the altcha package:

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

Alternatively, you can include the scripts via a <script> tag, using files from the dist_plugins directory or a 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>

It’s recommended to import plugins before the main altcha package to ensure they are registered before any widget instances are created.

Analytics Plugin

The Analytics plugin allows you to track form interactions using ALTCHA Forms. It’s easy to enable and doesn’t require additional configuration:

import 'altcha/analytics';

For more details, refer to the HTML submissions documentation.

Obfuscation Plugin

The Obfuscation plugin is designed to protect sensitive data, such as email addresses and phone numbers, by making them difficult for bots to scrape:

import 'altcha/obfuscation';

After enabling this plugin, configure the obfuscated attribute on your widget as described in the data obfuscation documentation.

Upload Plugin

The Upload plugin facilitates file uploads from type=file inputs in custom HTML forms, seamlessly integrating with ALTCHA Forms. It supports automatic uploads and end-to-end encryption (E2E) for files:

import 'altcha/upload';

For more information, see the HTML submissions documentation.

Advanced Usage

Direct Access

The ALTCHA widget exports a getPlugin(name) function, which returns an instance of the specified plugin. This allows you to interact with the plugin directly. For example, to add a file using the Upload plugin:

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

Creating Custom Plugins

If you need functionality beyond what the built-in plugins offer, you can create your own plugin. Here’s a minimal example of how to structure a custom plugin:

class MyPlugin {
  static pluginName = 'myplugin';

  constructor(context) {
    // Initialization code for your plugin
  }

  destroy() {
    // Cleanup code when the plugin is destroyed
  }
}

// Register your plugin globally
if (typeof globalThis.altchaPlugins !== 'object') {
  globalThis.altchaPlugins = [];
}
globalThis.altchaPlugins.push(MyPlugin);

The plugin constructor receives a context argument containing the el (the widget’s HTML element) and other helpful methods:

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