Skip to content
ALTCHA ALTCHA ALTCHA

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:

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://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:

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

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

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, or use the official API for easier and faster integration.

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: onfocus, onload, onsubmit).
  • blockspam - Only used in conjunction with the spamfilter option. If enabled, it will block form submission and fail verification if the Spam Filter returns a negative classification. This effectively prevents submission of the form.
  • expire - The challenge expiration (duration in milliseconds).
  • hidefooter - Hide the footer (ALTCHA link).
  • hidelogo - Hide the ALTCHA logo.
  • maxnumber - The max. number to iterate to (defaults to 1,000,000).
  • name - The name of the hidden field containing the payload (defaults to “altcha”).
  • refetchonexpire - Automatically re-fetch and re-validate when the challenge expires (defaults to true).
  • spamfilter - Enable the Spam Filter feature.
  • strings - JSON-encoded translation strings. Refer to customization.
  • verifyurl - Enable server-side verification by configuring the URL to use for verification requests. This option can be used in conjunction with spamfilter to enable server-side verification.
  • workers - The number of workers to utilize for PoW (defaults to navigator.hardwareConcurrency || 8).

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:

  • 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:

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

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.