Widget Integration

Integrating ALTCHA into your website or web app is straightforward and can be done within minutes.

The widget performs the user verification by computing the proof-of-work challenge and when used with the ALTCHA Sentinel, it also provides necessary UI for the optional code challenge.

Migrating from v2

If you’re currently using the v2 widget, upgrade to the improved v3 for the latest features and enhancements.

Installation via NPM

Install the package:

npm install altcha

Import it into your project:

import "altcha";

Alternatively, download the script

Download the ALTCHA script from GitHub or use the CDN:

https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js

To integrate the widget, add the script to your website:

<script async defer src="/altcha.js" type="module"></script>

For optimal integration, place the script tag within the <head> section.

Examples

Mobile

Flutter

React Native

Using `<altcha-widget>`

The ALTCHA widget functions as a Web Component and utilizes the browser’s internal capabilities to register a new tag <altcha-widget>. Integrate this tag within your forms:

<altcha-widget challenge="{YOUR_SERVER_HERE}"></altcha-widget>

Configure the challenge with your server’s address.

Usage with ALTCHA Sentinel

When using ALTCHA Sentinel for challenge generation, configure the widget with your Sentinel endpoint URL:

<altcha-widget
  challenge="https://sentinel.example.com/v1/challenge?apiKey=key_..."
></altcha-widget>

Where to find these values:

Endpoint URL: This is your Sentinel instance’s base URL with /v1/challenge path
API Key: A unique key authenticating your application with Sentinel

Both values are available in your Sentinel app.

Internationalization (i18n)

ALTCHA supports 50+ languages, allowing you to deliver a localized experience to your users. See the Internationalization guide for setup and configuration details.

Themes and Customization

Customize the widget’s appearance to match your UI and branding. Refer to the Customization guide for available options and examples.

Content Security Policy (CSP)

The default Web Component bundle includes styles and a Web Worker in a single file. If you are using a strict CSP, additional configuration may be required. See the CSP guide for details.

Configuration

Programmatic Configuration

The widget provides a global $altcha object to manage defaults, register new algorithms, or add custom translations.

To update an existing widget instance, use the .configure() method. This is the preferred way to handle complex objects or functions that cannot be passed via HTML attributes.

// Set defaults for all future widget instances:
$altcha.defaults.set({
  challenge: 'https://api.example.com/challenge',
  debug: true
});

// Update a specific instance dynamically:
const widget = document.querySelector('altcha-widget');
widget.configure({
  workers: 2,
  language: 'fr'
});

Attribute Configuration

For simple implementations, the widget supports a subset of configuration options directly as HTML attributes. For more advanced properties, use the programmatic approach above.

Supported Attributes:

<altcha-widget
  auto="off"
  challenge="https://api.example.com/challenge"
  configuration='{"delay": 500}'
  display="standard"
  language="en"
  name="altcha"
  theme="default"
  type="checkbox"
  workers="4"
></altcha-widget>

The configuration attribute accepts a JSON-encoded string, allowing you to pass complex settings directly in your HTML markup.

Core Settings

name: The name attribute of the hidden input field containing the payload. (Default: "altcha")
challenge: The challenge data or the URL to fetch a new challenge from.
type: Visual style of the interaction element ('native', 'checkbox', or 'switch').
language: The ISO alpha-2 language code for localization (requires corresponding i18n file).
workers: The number of Web Workers to spawn for proof-of-work calculations.

Automation & Timing

auto: Determines when verification triggers automatically ('off', 'onfocus', 'onload', or 'onsubmit').
minDuration: The minimum verification time in milliseconds; adds an artificial delay if the PoW is faster. (Default: 500)
retryOnOutOfMemoryError: Automatically attempts to restart verification with fewer workers if the browser runs out of memory (Argon2 and Scrypt only).

UI & Display

display: The visual layout mode ('standard', 'bar', 'floating', 'overlay', or 'invisible').
barPlacement: Vertical position of the widget when display is set to bar ('bottom' or 'top').
hideLogo: Hides the ALTCHA logo icon.
hideFooter: Hides the “ALTCHA” attribution link.
validationMessage: Custom validation message for the HTML5 setCustomValidity API.

floatingAnchor: The element or CSS selector the floating UI attaches to. Defaults to the first submit button.
floatingPlacement: Preferred position relative to the anchor ('auto', 'bottom', or 'top').
floatingOffset: Vertical offset in pixels between the UI and its anchor. (Default: 12)
floatingPersist: Whether the floating widget remains visible after successful verification.
popoverPlacement: Preferred position of popovers relative to the widget ('auto', 'bottom', or 'top').

codeChallengeDisplay: UI layout for the code-challenge modal ('standard', 'overlay', or 'bottomsheet').
overlayContent: CSS selector for an element to be mirrored inside the overlay modal.
audioChallengeLanguage: Forces a specific language for audio-based challenges.
disableAutoFocus: Prevents the code-challenge modal from stealing focus when opened.

Advanced & Debugging

debug: Enables verbose logging in the browser console.
test: Mocks a successful verification for testing environments.
mockError: Forces the widget into a failed state for UI testing.
fetch: A custom fetch implementation for network requests.
humanInteractionSignature: Whether the collector for HIS is enabled (Default: true).
setCookie: When configured, sends the payload as a cookie.
timeout: Verification timeout in milliseconds (Default: 90_000).
verifyFunction: A custom verification handler that overrides default network verification.

Cookies

By default, the widget sends the ALTCHA payload as a form field by creating a hidden input. It can also be configured to send the payload via a cookie.

To enable this behavior, use the setCookie configuration option:

widget.configure({
  setCookie: {
    name: 'altcha',
    path: '/'
  }
});

setCookie accepts the following cookie options:

interface SetCookieOptions {
  domain?: string;
  name?: string;
  maxAge?: number;
  path?: string;
  sameSite?: string;
  secure?: boolean;
}

Methods

configure(options) - Configures the widget with the given options. See Configuration options above.
getConfiguration() - Returns the current configuration.
getState() - Returns the current state of the widget.
show() - Displays the widget (used in some display modes).
hide() - Hides the widget (used in some display modes).
reset(state?, err?) - Resets the internal state, optionally with an error.
setState(state, err?) - Manually sets the specified state, optionally with an error.
updateUI() - Force UI update or reposition, for example for the floating display mode.
verify() - Initiates the verification process.

Events

codechallenge - Triggers when code-challenge verification is requested.
expired - Triggers when the challenge expires.
load - Triggers when the widget loads. The exported methods become available after this event.
outofmemory - Triggers when an Out-Of-Memory error is received (Argon2 and Scrypt only).
serververification -Triggers upon a server verification.
statechange - Triggers whenever an internal state changes.
verified - Triggers when the challenge is verified.

enum State {
  CODE = 'code',
  ERROR = 'error',
  VERIFIED = 'verified',
  VERIFYING = 'verifying',
  UNVERIFIED = 'unverified',
  EXPIRED = 'expired'
}

Using events:

const widget = document.querySelector('altcha-widget');
widget.addEventListener('statechange', (ev) => {
  // See enum State above
  console.log('state:', ev.detail.state);
});

Both programmatic configuration and event listeners have to called/attached after the ALTCHA script loads, such as within window.addEventListener('load', ...).

Caveats

Secure context requirement

The widget utilizes the browser’s built-in subtle.crypto interface to compute solutions securely. It’s essential to note that this cryptographic interface is exclusively available in a secure context, commonly implemented through HTTPS.

The widget necessitates a secure HTTPS connection to operate. Websites served over insecure HTTP connections will not support the widget’s functionality due to the absence of the required cryptographic interface. To ensure seamless widget operation, always serve your website securely via HTTPS.
JavaScript dependency

The widget operates with JavaScript and relies on its execution environment to perform computation and submission functions. Consequently, JavaScript-enabled browsers are a prerequisite for users to interact successfully with the widget.

When integrating the widget into website forms, consider that users without JavaScript enabled in their browsers will be unable to utilize or submit forms protected by the widget. Ensure your audience is aware of this requirement for seamless form submission.

Having Troubles?

See the troubleshooting guide.