Website Integration

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

The easiest method is to utilize our Web Component widget (check out the demo on the main page).

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://eu.altcha.org/js/latest/altcha.min.js

or jsdelivr.net:

https://cdn.jsdelivr.net/npm/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

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:

<form>
  <altcha-widget
    challengeurl="{YOUR_SERVER_HERE}"
  ></altcha-widget>
</form>

Configure the challengeurl with your server’s address, or use the official API for easier and faster integration.

Bundle Size

ALTCHA’s default bundle is lightweight, combining all assets, including CSS and the JavaScript Web Worker, into a single file. When GZIPped, it totals only 17 kB, making ALTCHA’s widget 94% smaller than reCAPTCHA.

Distribution	Size (GZIPped)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Configuration

Required options (at least one is required):

challengeurl - URL of your server to fetch the challenge from. Refer to server integration.
challengejson - JSON-encoded challenge data. If avoiding an HTTP request to challengeurl, provide the data here.

Additional options:

auto: Automatically verify without user interaction (possible values: off, onfocus, onload, onsubmit).
delay: Artificial delay in milliseconds before verification (defaults to 0).
expire: Challenge expiration duration in milliseconds.
floating: Enable floating UI (possible values: auto, top, bottom).
floatinganchor: CSS selector of the “anchor” to which the floating UI will be attached (defaults to the button[type="submit"] in the related form).
floatingoffset: Y offset from the anchor element for the floating UI in pixels (defaults to 12).
hidefooter: Hide the footer (ALTCHA link).
hidelogo: Hide the ALTCHA logo.
maxnumber: Max number to iterate to (defaults to 1,000,000).
name: Name of the hidden field containing the payload (defaults to “altcha”).
strings: JSON-encoded translation strings. Refer to customization.
refetchonexpire: Automatically re-fetch and re-validate when the challenge expires (defaults to true).
workers: Number of workers to utilize for PoW (defaults to navigator.hardwareConcurrency || 8, max value 16).
workerurl: URL of the Worker script (defaults to ./worker.js, only works with external build).

Spam Filter-related options:

blockspam: Only used with the spamfilter option. If enabled, it will block form submission and fail verification if the Spam Filter returns a negative classification. This prevents form submission.
spamfilter: Enable Spam Filter.
verifyurl: URL for server-side verification requests. This option is automatically configured when the spamfilter option is used. Override this setting only if using a custom server implementation.

Data Obfuscation options:

obfuscated: The obfuscated data provided as a base64-encoded string (requires altcha/obfuscation plugin). Use only without challengeurl/challengejson.

Development / testing options:

debug - Print log messages in the console.
mockerror - Causes the verification to always fail with a “mock” error.
test - Generates a “mock” challenge within the widget, bypassing the request to challengeurl.

Events

load - Triggers when the widget loads. The exported methods become available after this event.
serververification - Triggers during server-side verification when utilizing the API.
statechange - Triggers whenever an internal state changes.
verified - Triggers when the challenge is verified.

Using events:

document.querySelector('#altcha').addEventListener('statechange', (ev) => {
  // state can be: unverified, verifying, verified, error
  console.log('state:', ev.detail.state);
  if (ev.detail.state === 'verified') {
    // payload contains base64 encoded data for the server
    console.log('payload:', ev.detail.payload);
  }
});

Content Security Policy (CSP)

The default distribution bundle of the WebComponent includes styles and the worker in a single file. Since the web worker is executed from a Blob, you need to add the blob: source to your CSP:

Content-Security-Policy: script-src 'self'; worker-src 'self' blob:

Bundling everything into a single file might cause issues with strict CSP rules. For strict CSP compliance, consider using the scripts located in the /dist_external directory or import the external build:

import 'altcha/external/altcha.js';

With strict CSP, you’ll need to include these parts separately:

altcha/external/altcha.js - The WebComponent without injected CSS and WebWorker.
altcha/external/worker.js - The WebWorker.
altcha/altcha.css - CSS for the Widget.

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.