Skip to main content

Detailed API Description

Exported Functions​

AlanCaptcha.widgetUI(widget: HTMLElement): Promise<WidgetUI>​

This function initializes the widget with UI. If there already is a widget registered on the given element, the instance will be returned.

When the attribute data-autotrigger="false" is set, the widget will be initialized in semi-automatic mode and not start solving challenges automatically when the user interacts with the form the widget is contained.

All parameters have to be set as HTML attributes on the element. A list of all available parameters can be found in here.

Usage Example:

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

AlanCaptcha.widget(arg: HTMLElement | AlanCaptchaWidgetConfig): Widget​

This function initializes the widget in manual mode when a parameter of type AlanCaptchaWidgetConfig is passed. Meaning, the widget will not have any UI and you have to handle everything manually.

When an HTMLElement is passed, the function will return the instance of the widget that is registered on the given element or otherwise throw an error.

Usage Example:

const widgetReference: Widget = AlanCaptcha.widget({
    element: document.getElementById("alanElement"),
    sitekey: 'YOUR-SITE-KEY',
    monitortag: 'YOUR-MONITOR-TAG',
});

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

A detailed description of all parameters can be found here.

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.

Parameters​

There are two ways to pass parameters:

  • When using the widgetUI function or automatic initialization, all parameters have to be set as HTML attributes on the element. The parameter names have to be prefixed with data-, e.g. data-sitekey, data-lang, etc.
  • When using the widget function, all parameters have to be passed as an object of type AlanCaptchaWidgetConfig.

element​

Available for:

  • data-*: ❌
  • AlanCaptchaWidgetConfig: ✅

optional

The HTML element which should hold the widget object. Can be used later to retrieve the widget reference using AlanCaptcha.widget(element: HTMLElement) or AlanCaptcha.widgetUI(element: HTMLElement).

sitekey​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ✅

required

Your ALAN Captcha SiteKey. This is required to identify your ALAN Captcha account and to retrieve challenges. Can be found in your ALAN Captcha Admin Panel.

monitortag​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ✅

optional

The Monitor Tag to use for this widget. This is used to track the usage of the widget in your ALAN Captcha Admin Panel. If not set, the default Monitor Tag 'general' will be used. A list of all Monitor Tags can be found in the ALAN Captcha Admin Panel.

difficulty​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ✅

optional

The difficulty of the challenge. Higher difficulty means longer calculation times.

This parameter can only be set to a higher value than the difficulty of the SiteKey. If not set, the difficulty of the SiteKey will be used.

numberofpuzzles​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ✅

optional

The numbers of puzzles for the requested challenge. More puzzles mean a higher difficulty and longer solving time.

This parameter can only be set to a higher value than the numberOfPuzzles of the SiteKey. If not set, the numberOfPuzzles of the SiteKey will be used.

autorun​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ❌

optional

Controls whether the widget should start getting and solving challenges automatically after initialization, even before the user starts to interact with the form. Default is false.

autotrigger​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ❌

optional

Controls whether the widget should instantiate in automatic mode or semi-automatic-mode. Default is true.

lang​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ❌

optional

The language used by the UI. Currently, we support 5 languages.

If this attribute is not set, the language set in the html tag of your document will be used as default if possible.

Supported values:

  • en
  • de
  • es
  • fr
  • it

Translations for the UI can also be overridden via data attributes. The following attributes can be used to override the default translations:

  • data-unverifiedtext
  • data-verifiedtext
  • data-retrytext
  • data-workingtext
  • data-starttext

submitbutton​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ❌

optional

Used to toggle the disabled state of your submit button depending on the current state of the widget (success, working, error). This means, the submit button is disabled until the captcha is solved.

The parameter submitbutton can be set to a css selector to your submit button. If not set, the submit button will not be toggled.

solutionname​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ❌

optional

Used to alter the name of the hidden form input field that contains the solution to the captcha. Default value is alan-solution.

clientidentifier​

Available for:

  • data-*: ✅
  • AlanCaptchaWidgetConfig: ✅

optional

Used to identify the client that is requesting the challenge. Currently used for debugging purposes only.

Functions​

WidgetUI and Widget both provide the following functions:

isReadyToProcessNewChallenge(): boolean​

Returns true if the widget is ready to process a new challenge. This means the widget is not currently requesting a new challenge, there is no current challenge being solved and no already solved challenge present. Otherwise, returns false.

isWaitingForNewChallengeResponse(): boolean​

Returns true if the widget is currently waiting for a response from the server after requesting a new challenge. This means the widget is in the process of retrieving a new challenge and has not yet received a response. Otherwise, returns false.

Will return true after the requestNewChallenge() function is called and before the response is received from the server.

isChallengeReceived(): boolean​

Returns true if the widget has received a challenge from the server. This means the widget has successfully requested a new challenge and is ready to start solving it. Otherwise, returns false.

This will be the case after calling requestNewChallenge() and receiving a response from the server with a challenge.

isChallengeSolved(): boolean​

Returns true if the widget has successfully solved a challenge. This means the solution is ready to be submitted. Otherwise, returns false.

isChallengeSolvingInProgress(): boolean​

Returns true if the widget is currently solving a challenge. This means the widget is in the process of solving a challenge and has not yet finished calculating the solution. Otherwise, returns false.

requestNewChallenge(): Promise<void>​

Requests a new challenge from the server. This will start the process of retrieving a new challenge and will return a promise that resolves when the challenge is received.

Will throw an error if the widget is currently solving a challenge.

startSolvingPuzzles(): Promise<void>​

Starts the process of solving the puzzles for the current challenge. The returned promise has no special meaning.

To be notified when the challenge is solved, you can subscribe to the onChallengeSolved event.

Will throw an error if no challenge has been received yet.

abortSolvingPuzzles(): void​

Aborts the current challenge solving process.

Challenge solving can be restarted by calling startSolvingPuzzles() again. When no new challenge is requested in the meantime, the widget will restart solving the same challenge.

reset(): void​

Resets the widget to its initial state. This means the widget will not have any current challenge, no already solved challenge and will be ready to process a new challenge.

If solving is in progress, it will be aborted.

getLastSolvedChallenge(): SolvedChallenge | null​

Returns the last solved challenge. This will be null if no challenge has been solved yet.

WidgetUI additionally provides:

addEventListeners(): void​

Can be used on widgets that were initialized with semi-automatic handling to add all event listeners that are required for the widget to work automatically.

Meaning it transforms a semi-automatic widget into an automatic one.

Events​

Events will be dispatch by the widget to enable you to react to certain actions.

To subscribe the these events you can use the addEventListener function on the widget reference. The events will be of type CustomEvent and will contain a detail property with the relevant data.

Available events:

onChallengeReceived​

This event is triggered after calling requestNewChallenge() and the widget has received a new challenge from the server. The event will contain the challenge data in the detail property.

The detail property will look like this:

{
    "challenge": {
        "id": "0d2bf54a38284b028d635af9630c95", // the challenge id
        "version": 2, // version of the puzzle json format
        "puzzles": [
            {
                "id": "00c2127d1699f44a770f7d2b8d6dd6", // puzzle id
                "t": "sha256", // type of the algorythm
                "difficulty": 7, // difficulty of the puzzle
                "hb": "2107668e43983eea4711",
                "r": 1 // number of hashing-iterations
            },
            // more puzzles ...
        ]
    }
}

onChallengeSolvingStarted​

This event is triggered after calling startSolvingPuzzles() and the widget has started solving the puzzles for the current challenge. The event will contain the challenge data in the detail property.

onPuzzleSolvingStarted​

After calling startSolvingPuzzles() this event is triggered every time a new puzzle is started to be solved. The event will contain the current challenge data, the puzzle id of the puzzle to be solved and how many puzzles of the challenge have been solved so far in the detail property.

The detail property will look like this:

{
    "challenge": {...},
    "puzzle": "0d2bf54a38284b028d635af9630c95", // the puzzle that will be solved next
    "puzzlesSolved": 0 // number of puzzles solved so far
}

onPuzzleSolved​

Once a single puzzle is solved, this event is emitted. The event will contain the current challenge data, the puzzle id of the solved puzzle and how many puzzles of the challenge have been solved so far in the detail property.

The detail property will look like this:

{
    "challenge": {...},
    "puzzle": "0d2bf54a38284b028d635af9630c95", // the puzzle that has been solved
    "puzzlesSolved": 1 // number of puzzles solved so far
}

onChallengeSolved​

This event is emitted, when the challenge is solved and the solution is ready to be submitted. The event will contain the current challenge data and the solution payload in the detail property.

The detail property will look like this:

{
    "challenge": {...},
    "solutionPayLoad": {
        "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjYXB0Y2hhIiwiZXhwIjoxNzIwNjAyMTc1LCJuYmYiOjE3MjA2MDE4NzUsImlhdCI6MTcyMDYwMTg3NSwianRpIjoiNGMzNmQ1ZjQ5YmE0YmM0OTE2ZGY2MDhiNzE3YWE3MTBiNmNhYWQ5OCIsIm9yaWdpbiI6Imh0dHA6Ly8xMjcuMC4wLjE6ODEyMyIsIm1vbml0b3JUYWciOiIiLCJjaGFsbGVuZ2UiOnsiaWQiOiI2MWU5YTM1MzY3MDFkNTYyYjJlYjE1YTJiYmQyMjQiLCJ2ZXJzaW9uIjoyLCJwdXp6bGVzIjpbeyJpZCI6Ijg1YTc3NmY3M2MxNjRjMTUxZGIzYTJmYjdhN2M2MiIsInQiOiJzaGEyNTYiLCJyYW5kIjoiNTU5NzQ4ZjgiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzU1OTc0OGY4IiwiciI6MX0seyJpZCI6ImMyNTVkYTdiMjA5YmFiMjNkNGFiNmI4Njk4OWI3MyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiMzhmZWM2NWMiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzM4ZmVjNjVjIiwiciI6MX0seyJpZCI6IjFmODk1NDdiZmQ2MWJlNDg1YTZhMDQzZWQ4NDJkNyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiOWFjZTE5YzciLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzlhY2UxOWM3IiwiciI6MX0seyJpZCI6ImNkYmVkOGZlMzE4OWQxNzIyNjJkMDkxODNkNGQzNCIsInQiOiJzaGEyNTYiLCJyYW5kIjoiY2JhZGQ3NmIiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxM2NiYWRkNzZiIiwiciI6MX0seyJpZCI6IjMxYzE0MjYyODMxODY5YWRlMWNlYWYwYjZhMTI0NyIsInQiOiJzaGEyNTYiLCJyYW5kIjoiNDk3NGUzM2EiLCJkaWZmaWN1bHR5Ijo3LCJoYiI6IjIxMDc2NjhlNGQxMzQ5NzRlMzNhIiwiciI6MX1dfSwic2l0ZUtleSI6Imx4ekdzaWE4UGxNQXJpSVczdG03VjZpQUVBdW5PWlFPYmhSalE2Q2YifQ.qNTEloEQey3lEjZFSv096RoeldunbLwuUq4wW1aI-bE",
        "solutions": [
            {
                "id": "31c14262831869ade1ceaf0b6a1247", // puzzle id
                "solution": "000000000111" // solution hash
            },
            // more solutions ...
        ]
    }
}