Migrate from Google reCAPTCHA

The following tutorial will guide you on how to migrate from Google reCAPTCHA to TrustCaptcha on your website.

You should have already completed the following steps before you start to integrate TrustCaptcha into your website.

1. Read Get-Started: Get a quick overview of the concepts behind TrustCaptcha and the integration process in get started.

2. Existing CAPTCHA: If you don’t have a CAPTCHA yet, sign in or create a new user account. Then create a new CAPTCHA.

Google reCAPTCHA and TrustCaptcha both rely on the same principle: your frontend creates a token and your backend verifies it. The main difference is how the widget looks and how the server-side verification works.

In practice, you will:

• Remove the reCAPTCHA scripts and the g-recaptcha widget (or your grecaptcha.execute() calls).
• Add the TrustCaptcha widget and your TrustCaptcha sitekey.
• Replace the token name you send to your backend (g-recaptcha-response) with tc-verification-token.
• Replace your server-side verification call to Google with TrustCaptcha result validation.

Follow these steps to migrate from Google reCaptcha to TrustCaptcha.

Most reCAPTCHA integrations include a script tag and either a widget element or JavaScript execution code.

Typical examples you may remove:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<div class="g-recaptcha" data-sitekey="<your_recaptcha_site_key>"></div>

Depending on the version, you might also have:

• a different script (for example .../recaptcha/enterprise.js)
• JavaScript like grecaptcha.execute()
• callbacks like onSubmit(token) or data-callback="..."

Remove these pieces from your page and from your frontend logic. We will replace them with the TrustCaptcha widget and TrustCaptcha events.

TrustCaptcha provides a web component called trustcaptcha-component. It must be placed inside a <form> element and needs a TrustCaptcha sitekey.

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

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

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

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

When TrustCaptcha completes, it automatically writes a hidden form field named tc-verification-token. You can also listen to the captchaSolved event if you submit the form by JavaScript.

For detailed frontend integrations, use the guides below.

With reCAPTCHA, the token is typically available as g-recaptcha-response. With TrustCaptcha, it is tc-verification-token.

If you submit your form normally, you usually only need to read a different field name on the server.

If you submit via JavaScript, you can read the token from the event:

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

  trustcaptchaComponent.addEventListener('captchaSolved', (event) => {
    const verificationToken = event.detail;
    // Send verificationToken to your backend (e.g., JSON body).
  });
</script>

With reCAPTCHA, you usually call Google’s siteverify endpoint (or, for Enterprise, a Google Cloud API) and then interpret fields like success and score.

With TrustCaptcha, you retrieve the verification result from our API using:

• the verification token from your frontend (tc-verification-token)
• the TrustCaptcha secret-key (from your CAPTCHA settings)

// Retrieving the verification result
let verificationResult;
try {
    verificationResult = await CaptchaManager.getVerificationResult("<your_secret_key>", "<verification_token_from_your_client>");
} catch (error) {
    // Fetch verification result failed - handle error
}

Then you decide what to do based on the returned result (for example, verificationPassed and the score).

// Act on the verification result (sample)
const threshold = 0.5;
if (!verificationResult.verificationPassed || verificationResult.score > threshold) {
    console.log("Verification failed or bot score > 0.5 – possible automated request.");
} else {
    console.log("Everything looks good - probably a human.");
}

Please follow the result validation overview, and (optionally) use one of the ready-made backend integrations.

You do not need four completely different migrations. The general flow is always the same (remove reCAPTCHA → add TrustCaptcha → validate on the server). The only differences are usually how you “trigger” verification and what your UI looked like.

If you used the checkbox version, you likely had a visible widget (<div class="g-recaptcha">...). TrustCaptcha also renders a small box, but it runs automatically and does not ask users to solve puzzles.

If your form previously relied on a “callback” after the checkbox, switch to:

• reading tc-verification-token on form submit, or
• listening to captchaSolved / captchaFailed.

If you used invisible reCAPTCHA, you often triggered it manually on submit (grecaptcha.execute()).

With TrustCaptcha you can do something similar:

• You can disable autostart (autostart="false") and trigger verification manually using startVerification().
• If you truly want no visible widget, TrustCaptcha also supports invisible="true", but it requires a license key. See the widget overview for details.

reCAPTCHA v3 is score-based and usually runs without a visible widget. TrustCaptcha also provides a bot score (score) and a clear decision (verificationPassed).

A simple migration approach is:

• Use the TrustCaptcha score the same way you used the reCAPTCHA v3 score.
• Start with a safe threshold (for example 0.5) and adjust it based on your environment and your spam/bot pressure.

Enterprise setups often add product-specific fields and a different server-side API. With TrustCaptcha, the flow stays the same as for all other TrustCaptcha integrations: widget → token → server-side result validation.

If your enterprise logic used actions, risk levels, or multiple thresholds, you can implement the same decision steps using verificationPassed, score, and your own multi-step rules.

Once you have successfully installed and configured TrustCaptcha on your website, you can use TrustCaptcha to its full extent. However, we still recommend the following additional technical and organizational measures:

• 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.

• Data protection: 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: 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.