Salta ai contenuti
ALTCHA ALTCHA ALTCHA

Questi contenuti non sono ancora disponibili nella tua lingua.

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 Sentinel, it also provides necessary UI for the optional code challenge.

Installation via NPM

Install the package:

Terminal window
npm install altcha

Import it into your project:

form.js
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:

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

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

Examples

React
Vue
Svelte
Solid
Lit
Angular

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.html
<form>
  <altcha-widget
    challengeurl="{YOUR_SERVER_HERE}"
  ></altcha-widget>
</form>

Configure the challengeurl with your server’s address.

Usage with Sentinel

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

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

Where to find these values:

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

Both values are available in your Sentinel app.

Internationalization (i18n)

ALTCHA supports 48+ languages. You can import individual language translations or a bundle that includes all of them.

To import all translations:

import 'altcha/i18n/all';

To import specific languages only:

import 'altcha/i18n/de';
import 'altcha/i18n/fr-fr';

Alternatively, you can import the combined bundle, which includes both the widget and all translations:

import 'altcha/i18n';

When using the CDN:

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

Language Detection

The widget automatically detects the language from:

  • The <html lang="..."> attribute
  • The user’s browser settings (navigator.languages)

To override the language manually, use the language attribute:

<altcha-widget language="de"></altcha-widget>

Customizing Translations

You can override default translations by updating the global altchaI18n registry (globalThis.altchaI18n or window.altchaI18n):

import 'altcha/i18n/de';


globalThis.altchaI18n.set('de', {
  ...globalThis.altchaI18n.get('de'),
  label: 'Ich bin ein Mensch' // Custom label
});

Supported Languages

  • Afrikaans (af)
  • Arabic (ar)
  • Bengali (bn)
  • Basque (eu)
  • Bosnian (bs)
  • Bulgarian (bg)
  • Catalan (ca)
  • Chinese - Simplified (zh-cn)
  • Chinese - Traditional (zh-tw)
  • Croatian (hr)
  • Czech (cs)
  • Danish (da)
  • Dutch (nl)
  • English (en)
  • Estonian (et)
  • Finnish (fi)
  • French - Canada (fr-ca)
  • French - France (fr-fr)
  • German (de)
  • Greek (el)
  • Hebrew (he)
  • Hindi (hi)
  • Hungarian (hu)
  • Icelandic (is)
  • Indonesian (id)
  • Italian (it)
  • Irish (ga)
  • Japanese (ja)
  • Korean (ko)
  • Latvian (lv)
  • Lithuanian (lt)
  • Maltese (mt)
  • Marathi (mr)
  • Norwegian Bokmål (nb, no)
  • Polish (pl)
  • Portuguese - Brazil (pt-br)
  • Portuguese - Portugal (pt-pt)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish - Spain (es-es)
  • Spanish - Latin America (es-419)
  • Swedish (sv)
  • Tamil (ta)
  • Telugu (te)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Urdu (ur)
  • Vietnamese (vi)

Regional packages:

  • All (all)
  • Americas (americas)
  • Asia (asia)
  • Europe (europe)

Widget Customization

To tweak and adjust the widget to match your aesthetics and UI, refer to the Widget Customization guide.

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).
  • credentials: Whether to include credentials with the challenge request (possible values: omit, same-origin, include).
  • customfetch: A custom fetch function for retrieving the challenge.
    Accepts url: string and init: RequestInit as arguments and must return a Response.
  • delay: Artificial delay in milliseconds before verification (defaults to 0).
  • disableautofocus: If true, prevents the code-challenge input from automatically receiving focus on render (defaults to false).
  • 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).
  • floatingpersist: Whether to “persist” (keep visible) the floating widget after verification (possible values: true | false | focus; defaults to false, meaning the widget will hide).
  • hidefooter: Hide the footer (ALTCHA link).
  • hidelogo: Hide the ALTCHA logo.
  • id: The checkbox id attribute. Useful for multiple instances of the widget on the same page.
  • language: The ISO alpha-2 code of the language to use (the language file be imported from altcha/i18n/*).
  • 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).

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

  • code - Triggers when code-challenge verification is requested.
  • load - Triggers when the widget loads. The exported methods become available after this event.
  • sentinelverification - Triggers upon a verification with ALTCHA Sentinel.
  • serververification - (Deprecated) Triggers upon a server verification (only in conjunction with spamfilter).
  • statechange - Triggers whenever an internal state changes.
  • verified - Triggers when the challenge is verified.

Using events:

form.js
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:

form.js
import 'altcha/external';

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

  • altcha/external - The WebComponent without injected CSS and WebWorker.
  • altcha/worker - 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.

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 about 29 kB, making ALTCHA’s widget about 90% smaller than reCAPTCHA.

DistributionSize (GZIPped)
ALTCHA29+ kB
ALTCHA with all translations42+ kB
hCaptcha48+ kB
reCAPTCHA270+ kB

Accessibility

For details on WCAG compliance and accessibility best practices, see the WCAG compliance guide.

Having Troubles?