Frontend Implementation
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).
Below you will find a current list of currently provided libraries:
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 | Sitekey of the CAPTCHA. You can find this on the administration page of your CAPTCHA. | |
language | Display language of the Trustcaptcha component. Available languages / modes: auto (Auto language detection, fallback English), be (Belarusian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), fi (Finnish), fr (French), hr (Croatian), hu (Hungarian), it (Italian), lb (Luxembourgish), lt (Lithuanian), lv (Latvian), nl (Dutch), no (Norwegian), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sv (Swedish), tr (Turkish) Default: auto (Auto language detection) | |
theme | Display mode of the Trustcaptcha component. Available modes: light (Light), dark (Dark), media (Device setting) Default: light (Light) | |
autostart | Setting whether the CAPTCHA should start automatically. Available settings: active, disabled Default: active | |
bypassToken | For automated tests, bypass keys can be created in the settings, with which the captcha is always successfully passed. | |
mode | Set the data mode of the captcha. Must match the settings of the captcha. Available modes: standard, minimal (minimal data mode) Default: standard | |
tokenFieldName | 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 | |
reset() | Resets the Trustcaptcha component. | |
captchaSolved | Triggered when the CAPTCHA has been successfully solved. | |
captchaFailed | 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. |
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. |
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="disabled" directly on the Trustcaptcha component.