Technical details of the frontend

Below is explained how to integrate Trustcaptcha into your website.

Supported Technologies

You can generally use Trustcaptcha with all common technologies and frameworks based on JavaScript. Supported are Server-Side Rendering (SSR), Static Site Generation (SSG), and Single-Page Applications (SPA). You can find instructions for integration here.

Below you will find a current list of currently provided libraries:

Angular

Javascript

React

Vue

Usage

Below you will learn how the basic concept of implementing the Trustcaptcha component in your frontend works.

Trustcaptcha Component

This is how or similarly the implementation of the Trustcaptcha component on your website can look like. Please refer to the respective tutorial that matches your programming language or framework.

Please note that the Trustcaptcha component must be located within a form element. Also, specify the site-key of your CAPTCHA.

The Trustcaptcha component contains a range of properties, methods, and events. Below you will find a listing of all existing properties and events.

Name	Type	Description
sitekey	Property	Sitekey of the CAPTCHA. You can find this on the administration page of your CAPTCHA.
width	Property	Width of the Trustcaptcha component. Available settings: fixed (fixed maximum width), full (maximum possible width) Default: fixed
language	Property	Display language of the Trustcaptcha component. Available languages / modes: auto (Auto language detection, fallback English), ar (Arabic), be (Belarusian), bg (Bulgarian), bs (Bosnian), ca (Catalan), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hi (Hindi), hr (Croatian), hu (Hungarian), it (Italian), ko (Korean), lb (Luxembourgish), lt (Lithuanian), lv (Latvian), mk (Macedonian), nl (Dutch), no (Norwegian), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sq (Albanian), sr (Serbian), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese). Default: auto (Auto language detection)
theme	Property	Display mode of the Trustcaptcha component. Available modes: light (Light), dark (Dark), media (Device setting) Default: light (Light)
autostart	Property	Setting whether the CAPTCHA should start automatically. Available settings: true, false Default: true
license	Property	License key for special features such as 'slider', 'hideBranding' or 'invisible'. You can find the license key on your CAPTCHA management page.
slider	Property	Setting to display the slider. Requirement: The feature must be included in the CAPTCHA pricing plan, and the corresponding license key must be provided during implementation. Available settings: disabled, inline, popup Default: disabled
hide-branding	Property	Setting to hide the Trustcaptcha logo. Requirement: The feature must be included in the CAPTCHA pricing plan, and the corresponding license key must be provided during implementation. Available settings: true, false Default: false
invisible	Property	Setting to make the CAPTCHA invisible. Requirement: The feature must be included in the CAPTCHA pricing plan, and the corresponding license key must be provided during implementation. Available settings: true, false Default: false
bypass-token	Property	For automated tests, bypass keys can be created in the settings, with which the captcha is always successfully passed.
mode	Property	Set the data mode of the captcha. Must match the settings of the captcha. Available modes: standard, minimal (minimal data mode) Default: standard
token-field-name	Property	Name of the field within the form in which the verification token is provided after successful completion of the verification process. Default: tc-verification-token
startVerification()	Method	Manual start of the Trustcaptcha component.
reset()	Method	Resets the Trustcaptcha component.
captchaStarted	Event	Triggered when the CAPTCHA is started.
captchaSolved	Event	Triggered when the CAPTCHA has been successfully solved.
captchaFailed	Event	Triggered when solving the CAPTCHA has failed.
captchaReset	Event	Triggered when solving the CAPTCHA has failed.

The Verification Token

The captchaSolved event returns the verification token when the CAPTCHA is successfully solved. You can access this via $event.detail. Save it if necessary and send it with your other form data to your backend.

Once you have transmitted the verification token to your backend, you need to retrieve the verification result and determine your further actions based on it. Please refer to the tutorial The Backend for this.

Error Message

If the CAPTCHA fails, the Trustcaptcha component returns an error message via the captchaFailed event. You can use this to determine further steps or to correct the error directly. You can access the error message via $event.detail.

The error message includes an error code named errorCode. This provides information about the actual error and can be used to directly correct the error or to implement error handling.

Error Code (errorCode)	Description
UNKNOWN_ERROR	Unknown error.
NO_FORM_FOUND	No form found. Please note that the Trustcaptcha component must be within a form element.
COMMUNICATION_FAILURE	Communication failed. There may be problems with the internet connection or errors with the Trustcaptcha provider.
NO_SITE_KEY_SPECIFIED	No site key has been specified. Please take the site key from your captcha settings and provide it on your website.
SITE_KEY_NOT_VALID	The site key is not valid. Please check the stored site key.
MODES_NOT_MATCHING	The set captcha mode of the Trustcaptcha component does not match the set mode in the captcha settings.
CAPTCHA_NOT_ACCESSIBLE	The CAPTCHA is not accessible. Please check if the domain or IP address of your website is listed in the CAPTCHA settings.
POW_FAILURE	The cryptographic tasks were not correctly solved by the client.
PAYMENT_REQUIRED	The CAPTCHA is locked due to missing payment and a limited pricing plan. Please check your pricing plan and payment status or contact support.
LOCKED	The CAPTCHA is locked. Please contact support.
LICENSE_INVALID	The provided license key is invalid or does not match your CAPTCHA / the specified siteKey. Please verify the license key.
OPTION_NOT_AVAILABLE	The selected feature, such as 'hideBranding' or 'invisible', is currently not available. Please check your current pricing plan and the provided license key.

Helpful Information

Here you will find helpful tips and tricks about integrating the Trustcaptcha component into your frontend.

Configure autostart

Basically, the verification process starts automatically with the input or focus of input fields that are within the same form element. If this behavior is explicitly not desired for selected fields, it can be turned off by setting the property data-autostart="false" on the respective input field.

If you want to completely disable autostart for all input fields, simply set the property autostart="false" directly on the Trustcaptcha component.