Skip to main content

JS Widget API

The JS Widget API allows you to integrate ALAN Captcha into your web applications using JavaScript. This API is only required if you want to integrate ALAN Captcha into a custom web application. When using one of the official ALAN Captcha integrations, you don't need to use this API directly, as the integration will set up the widget for you. You can find the documentation for the official integrations in the Integration Guide.

Installation​

There are two ways to include the ALAN Captcha widget:

Option 1: Use the widget directly from our CDN

<script src="https://api.alancaptcha.com/widget/latest/widget.bundle.js"></script>

Option 2: Install the package via a package manager into your app

npm install @alancaptcha/widget

You can then import it into your app:

import * as AlanCaptcha from '@alancaptcha/widget'

Usage​

Once you have installed the widget and acquired your ApiKey and SiteKey, as described here, there are three options to embed the widget.

  • Automatic handling

    In this case, everything is done automatically. No further JavaScript is needed. You only need to provide a div with data attributes to provide your SiteKey. This is useful for standard one-page forms.

    <div class="alan-captcha" data-sitekey="YOUR-SITE-KEY"></div>

    Note that automatic handling is only available when installing the widget via script tag.

  • Semi-automatic handling

    A UI is provided, but you take control over when different actions occur. This can be useful if you want to trigger solving the puzzles, e.g., on click of a button.

  • Manual handling

    You have full control over what is done and when. No UI is provided. This allows for the most flexibility to meet your needs.

Automatic handling​

This implementation is the quickest and easiest to do. All you need to do is include a div with the class alan-captcha inside your HTML <form>.

<form>
    <div
        class="alan-captcha"
        data-sitekey="YOUR-SITE-KEY"
        data-lang="en"
        data-monitortag="MONITOR-TAG"
        data-submitbutton="submit-button-id">
    </div>
    <button type="submit" id="submit-button-id">Submit</button>
</form>

ALAN Captcha checks for newly added elements at runtime and initializes them automatically. It automatically adds the required UI and an <input type="hidden" name="alan-solution"> element, which contains the solution to the captcha as value. Requesting new challenges and solving them starts as soon as the user begins to interact with the surrounding <form>.

Since the solution is saved in the created hidden input field, the server can check this hidden input field.

Semi-automatic handling​

This type of implementation provides the same UI as automatic handling. The difference is that event handling and starting the solving process has to be done manually by the developer.

The simplest implementation looks like this:

  1. Include a <div> with the attribute data-autotrigger="false" in your HTML <form> to use as the widget container:

    <div
        id="alanContainer"
        class="alan-captcha"
        data-sitekey="YOUR-SITE-KEY"
        data-autotrigger="false">
    </div>

  2. Initialize and use the widget using JS:

    const widgetReference = await AlanCaptcha.widgetUI(document.getElementById("alanContainer"));

    widgetReference.addEventListener("onChallengeSolved", e => {
        console.log("Solutions: " + e.detail.solutionPayLoad);
    });

    await widgetReference.requestNewChallenge();
    await widgetReference.startSolvingPuzzles();

After the widget is initialized you can also use AlanCaptcha.widgetUI(...) or AlanCaptcha.widget(...) to get a reference to the widget.

const widgetReference = AlanCaptcha.widget(document.getElementById("alanContainer"));

Manual handling​

This type of implementation provides the most flexibility, but also requires the most work. It does not provide any UI and you have to handle everything manually.

A basic implementation looks like this:

const widgetReference = AlanCaptcha.widget({
      element: document.getElementById("alanElement"),
      sitekey: "YOUR-SITE-KEY",
      // more optional parameters
});

widgetReference.addEventListener("onChallengeSolved", e => {
    console.log("Solutions: " + e.detail.solutionPayLoad);
});

await widgetReference.requestNewChallenge();
await widgetReference.startSolvingPuzzles();

The element parameter is optional and is only required if you want to retrieve the widget reference later using AlanCaptcha.widget(document.getElementById("alanElement")).

It is important that your element does not contain the class alan-captcha, as this class is used to automatically initialize the widget in automatic and semi-automatic handling.

A detailed description of all parameters and functions can be found in the Detailed API Description.