Migrate from Cloudflare Turnstile

The following tutorial will guide you on how to migrate from Cloudflare Turnstile 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.

Cloudflare Turnstile and TrustCaptcha both work with a simple idea: your frontend produces a token and your backend verifies it. The migration is mostly about replacing the frontend widget and updating the server-side verification.

In practice, you will:

• Remove the Turnstile JavaScript and the cf-turnstile widget container from your pages.
• Add the TrustCaptcha dependency and the <trustcaptcha-component> web component.
• Replace the Turnstile token field (cf-turnstile-response) with the TrustCaptcha token field (tc-verification-token).
• Replace your server-side call to Cloudflare’s verification endpoint with TrustCaptcha result validation.

Follow these steps to migrate from Cloudflare Turnstile to TrustCaptcha.

In most Turnstile setups, you have two pieces that you need to remove:

1. The Turnstile script tag, for example:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

2. The Turnstile container element, for example:

<div class="cf-turnstile" data-sitekey="<your_turnstile_site_key>"></div>

If your code reads the Turnstile token from the form, you will usually see something like cf-turnstile-response. Remove that handling too (we will replace it with the TrustCaptcha token in the next steps).

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 want to send the token using JavaScript.

For detailed frontend integrations, use the guides below.

With Turnstile, the token is typically submitted via the hidden form input cf-turnstile-response. With TrustCaptcha, the field is called tc-verification-token.

If you submit your form normally, you can usually just read the different field name on the server.

If you submit via JavaScript, this is a simple pattern:

<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 Turnstile, you typically call Cloudflare’s verification endpoint (siteverify) and check if the token is valid.

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.

Cloudflare Turnstile offers three widget modes: Managed, Non-Interactive, and Invisible.

In TrustCaptcha, you typically have two ways to match your old behavior:

• Visible widget (most common): Use the default TrustCaptcha widget. It is a small box and runs automatically when the user interacts with the form.
• Invisible behavior: If you used Turnstile “Invisible” and want no visible widget at all, TrustCaptcha supports an invisible mode (invisible="true"), but it requires a license key. See the widget overview for details and options like invisible-hint.

If you previously used custom callbacks like “success” / “error”, you can switch to the TrustCaptcha events captchaSolved and captchaFailed. If you used a reset button, you can call reset() on the TrustCaptcha component.

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.