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 LogoAngular
JavaScript LogoJavascript
React LogoReact
Vue LogoVue

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 v1.4+
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 v1.6+
Property
License key for special features such as 'slider', 'hideBranding' or 'invisible'. You can find the license key on your CAPTCHA management page.
slider v1.7+
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 v1.6+
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 v1.6+
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 v1.3+
Property
For automated tests, bypass keys can be created in the settings, with which the captcha is always successfully passed.
mode v1.3+
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 v1.1+
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() v1.6.1+
Method
Manual start of the Trustcaptcha component.
reset()
Method
Resets the Trustcaptcha component.
captchaStarted v1.6+
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 v1.7+
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.

Release notes

Here you can see all the modifications and changes of the Trustcaptcha frontend-library.

Version
Date
Changes
1.7.3
Nov 19, 2024
  • Added: provide static umd javascript bundles from version 1.7
  • Added: cache rules for static assets
  • Changed: improve proof-of-work and privacy measures
1.7.2
Nov 8, 2024
  • Updated: links in the README.md files
1.7.1
Nov 5, 2024
  • Added: provide static cjs javascript bundles from version 1.7
  • Added: measures to optimize the captcha box in the future
  • Changed: replace company website with privacy url
1.7.0
Nov 1, 2024
  • Added: new captcha box slider security measure
  • Added: public javascript event captchaReset()
  • Changed: improve cache methods to improve loading performance of static javascript bundles files
  • Changed: improve text minification and text compression to improve loading performance
  • Changed: improve code to reduce code size
  • Changed: Improvement of privacy measures
  • Removed: language support for Armenian (hy), Azerbaijani (az), Bengali (bn), Hebrew (he), Indonesian (id), Japanese (ja), Kazakh (kk), Malay (ms), Persian (fa), Swahili (sw), Tagalog (tl), Tamil (ta), Thai (th), Urdu (ur), Vietnamese (vi)
  • Updated: Update internal dependencies
1.6.1
Oct 24, 2024
  • Added: public javascript function startVerification() to trigger the captcha box manually
  • Fixed: StencilJs downgraded to version 4.17.2 to fix vue issues
1.6.0
Oct 17, 2024
  • Added: captcha box hide branding option
  • Added: captcha box invisible option
  • Added: public javascript event captchaStarted()
  • Removed: remove old button shaped design
  • Updated: StencilJS updated to version 4.20.0
1.5.0
Sep 7, 2024
  • Added: add error message if captcha is locked
  • Added: add error message if captcha is temporary locked because of payment issues
1.4.2
Aug 14, 2024
  • Added: language support for Albanian (sq), Armenian (hy), Azerbaijani (az), Bosnian (bs), Bulgarian (bg), Catalan (ca), Estonian (et), Hebrew (he), Kazakh (kk), Macedonian (mk), Malay (ms), Persian (fa), Serbian (sr), Slovene (sl), Tamil (ta), Ukrainian (uk)
  • Changed: improve compatibility for screen readers
1.4.1
Aug 11, 2024
  • Fixed: issue with the provided static esm javascript bundle files
1.4.0
Aug 11, 2024
  • Added: add new checkbox shaped design
  • Added: captcha box width with option full and fixed
  • Added: language support for: Arabic (ar), Bengali (bn), Chinese (zh), Hindi (hi), Indonesian (id), Japanese (ja), Korean (ko), Swahili (sw), Tagalog (tl), Thai (th), Urdu (ur), Vietnamese (vi)
  • Added: provide static esm javascript bundles for version 1.2, 1.3 and 1.4
  • Changed: improve error display message on error COMMUNICATION_FAILURE
  • Deprecated: current button shaped design will be removed on version 1.6.0
1.3.2
Jul 3, 2024
  • Changed: improve captcha box design
  • Fixed: bug on auto language detection
1.3.1
May 3, 2024
  • Fixed: Issue in the build process
1.3.0
May 3, 2024
  • Added: auto language detection
  • Added: minimal data mode option
  • Added: bypass keys for testing purposes
  • Fixed: wrong display error on 422 server response
1.2.0
Mar 27, 2024
  • Added: dynamic names for honeypot field
  • Fixed: move proof-of-work calculation to web-workers to fix performance issues in different frameworks like angular and make proof-of-work more efficient
  • Fixed: privacy and performance issue while data collection and analysis
  • Fixed: cursor-design on disabled buttons
  • Updated: StencilJS updated to version 4.13.0
  • Updated: Update internal dependencies
1.1.1
Mar 18, 2024
  • Updated: privacy link in the captcha-box
  • Updated: and in links in the README.md files
1.1.0
Feb 29, 2024
  • Added: language support for Belarusian (be), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), French (fr), Greek (el), Hungarian (hu), Italian (it), Latvian (lv), Lithuanian (lt), Luxembourgish (lb), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Slovak (sk), Spanish (es), Swedish (sv), Turkish (tr)
  • Added: make verification token field name changeable
  • Added: switch off the autostart for certain input fields
  • Changed: design and behaviour of the loading spinner animation
  • Updated: StencilJS updated to version 4.12.4
1.0.1
Jan 23, 2024
  • Refactor: proof-of-work calculation
  • Refactor: unnecessary code
  • Updated: StencilJS updated to version 4.11.0
1.0.0
Jan 12, 2024
  • Release version
0.0.4
Jan 11, 2024
  • Open-Beta
0.0.3
Jan 11, 2024
  • Open-Beta
0.0.2
Nov 23, 2024
  • Open-Beta
0.0.1
Aug 15, 2024
  • Closed-Beta