JavaScript CAPTCHA

The following tutorial will guide you on how to integrate the TrustCaptcha CAPTCHA solution into your Go backend to retrieve and evaluate the CAPTCHA verification result.

Preparation

You should have already completed the following steps before you start with CAPTCHA widget integration in your in JavaScript frontend.

Read the basic Information: For a basic overview, please read the get started guide. We also recommend that you familiarize yourself with the technical concept of TrustCaptcha.
Existing CAPTCHA: If you don’t have a CAPTCHA yet, sign in or create a new user account. Then create a new CAPTCHA.
Existing JavaScript website: You need a JavaScript website in which you want to integrate the TrustCaptcha CAPTCHA widget.

Follow the steps below to integrate the TrustCaptcha CAPTCHA widget into your JavaScript frontend

1. Add dependency

Add the CAPTCHA dependency to your html file or globally into your JavaScript project.

Universal Module Definition (umd)

<script src="https://cdn.trustcomponent.com/trustcaptcha/2.1.x/trustcaptcha.umd.min.js"></script>

ECMAScript Modules (esm)

<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/2.1.x/trustcaptcha.esm.min.js"></script>

CommonJS (cjs)

<script src="https://cdn.trustcomponent.com/trustcaptcha/2.1.x/trustcaptcha.cjs.min.js"></script>

Insert the trustcaptcha-component into your HTML. It is important that the widget is located within a form element. Then set the required site-key. You can find this key in your CAPTCHA settings. Information on all other properties can be found in the CAPTCHA widget overview.

Important: Once the CAPTCHA has been solved, you will receive a so-called verification token. This is available as a hidden input field with the name tc-verification-token. You can also get the token via the JavaScript event captchaSolved of the trustcaptcha component. Then send the verification token to your backend and validate it there. You can find out more about this in result validation overview.

<form>
  <!-- your input fields -->

  <trustcaptcha-component
      sitekey="<your_site_key>"
  ></trustcaptcha-component>

   <!-- further input fields / submit button -->
</form>

<script>
  const trustcaptchaComponent = document.getElementsByTagName('trustcaptcha-component')[0];

  <!-- handle success -->
  trustcaptchaComponent.addEventListener('captchaSolved', (event) => {
    console.log('Verification token:', event.detail);
  });

  <!-- handle error -->
  trustcaptchaComponent.addEventListener('captchaFailed', (event) => {
    console.error(event.detail);
  });
</script>

Example implementation

The following example shows a possible implementation of the TrustCaptcha CAPTCHA widget in a JavaScript frontend.

The complete example including source code can be found on Github.

<head>
    <meta charset="UTF-8">
    <title>TrustCaptcha Testsystem</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-KK94CHFLLe+nY2dmCWGMq91rCGa5gtU4mk92HdvYe+M/SXH301p5ILy+dN9+nJOZ" crossorigin="anonymous">
    <script type="module" src="https://resources.trustcaptcha.com/1_9_x/trustcaptcha.js"></script>
</head>

<body class="py-5">
    <div class="d-flex justify-content-center">
        <div class="w-100" style="max-width: 640px;">
            <h1>Thymeleaf (Spring)</h1>
            Try Thymeleaf<br />
            <br/>
            <form th:if="${captchaSuccess == null}" th:action="'/'" method="post" th:object="${model}">
                <div class="mb-3">
                    <label for="messageInput" class="form-label">Message</label>
                    <textarea class="form-control" id="messageInput" placeholder="Write a message" rows="3" th:field="*{message}"></textarea>
                </div>
                <div class="mb-3">
                    <trustcaptcha-component
                        id="trustcaptchaComponent"
                        sitekey="<your_site_key>"
                        language="en"
                        theme="light"
                        token-field-name="myToken"
                    ></trustcaptcha-component>
                </div>
                <div class="d-grid gap-2">
                    <button class="btn btn-success" id="submitButton" disabled>Post new message</button>
                </div>
            </form>
            <div th:if="${verificationResult}" >
                <div class="alert alert-success mt-3" role="alert">
                    <strong>Message: </strong><span th:text="${message}"></span><br>
                    <strong>Passed: </strong><span th:text="${verificationResult.isVerificationPassed()}"></span><br>
                    <strong>Reason: </strong><span th:text="${verificationResult.getReason()}"></span><br>
                    <strong>Score: </strong><span th:text="${verificationResult.getScore()}"></span>
                </div>
                <div class="d-grid gap-2">
                    <button type="button" class="btn btn-primary" onclick="reloadPage()">Reload page</button>
                </div>
            </div>
        </div>
    </div>
</body>

<script>

   function reloadPage() {
       window.location.href = '/'
   }

   <!-- example, unused in this sample -->
   function resetCaptcha() {
       const trustcaptchaComponent = document.getElementById('trustcaptchaComponent');
       trustcaptchaComponent.reset();
   }

    <!-- Handle solve and fail event -->
   const trustcaptchaComponent = document.getElementById('trustcaptchaComponent');
    trustcaptchaComponent.addEventListener('captchaSolved', (event) => {
        console.log('Verification token:', event.detail);
        const submitButton = document.getElementById('submitButton');
        submitButton.disabled = false;
    });
    trustcaptchaComponent.addEventListener('captchaFailed', (event) => {
        console.error(event.detail);
    });
</script>

package com.trustcaptcha.sample.controller;

import com.trustcaptcha.library.CaptchaManager;
import com.trustcaptcha.library.exception.CaptchaFailureException;
import com.trustcaptcha.library.model.VerificationResult;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;

@Controller
public class SampleController {

  private final Logger logger = LoggerFactory.getLogger(SampleController.class);

  @GetMapping("/")
  public String getPage(Model model) {

    model.addAttribute("model", new PageModel());

    return "index";
  }

  @PostMapping(value = "/")
  public String postPage(@ModelAttribute PageModel pageModel, @RequestParam("tc-verification-token") String verificationToken, Model model) {

    // Retrieving the verification result
    VerificationResult verificationResult;
    try {
      verificationResult = CaptchaManager.getVerificationResult("<your_secret_key>", verificationToken);
    } catch (CaptchaFailureException e) {
      // Fetch verification result failed - handle error
      throw new RuntimeException(e);
    }

    // Act on the verification result
    if (!verificationResult.isVerificationPassed() || verificationResult.getScore() > 0.5) {
      logger.warn("Verification failed or bot score > 0.5 – possible automated request.");
    }

    model.addAttribute("model", new PageModel());
    model.addAttribute("message", pageModel.getMessage());
    model.addAttribute("verificationResult", verificationResult);

    return "index";
  }
}

package com.trustcaptcha.sample.controller;

public class PageModel {

  public String message;

  public PageModel() { this.message = ""; }

  public String getMessage() { return message; }

  public void setMessage(String message) { this.message = message; }
}

Next steps

Once you have integrated the TrustCaptcha widget into your frontend, please remember to check the verification token on the server side and evaluate the CAPTCHA result. You can find more information on this in result validation overview. We also recommend that you familiarize yourself with the following topics:

Security rules: You can find many security settings for your CAPTCHA in the CAPTCHA settings. These include, for example, authorized websites, CAPTCHA bypass for specific IP addresses, bypass keys, IP based blocking, geoblocking, individual difficulty and duration of the CAPTCHA, and much more. Learn more about the security rules.
Privacy & GDPR compliance: Include a passage in your privacy policy that refers to the use of TrustCaptcha. We also recommend that you enter into a data processing agreement with us to stay GDPR-compliant. Learn more about data protection.
Accessibility & UX: Customize TrustCaptcha to your website so that your website is as accessible as possible and offers the best possible user experience. More about accessibility.
Testing: If you use automated testing, make sure that the CAPTCHA does not block it. Learn more about testing.