Skip to main content

2. Adding The Widget

✅ A full working ideal frontend example can be found at the bottom of this page.

In addition you can find Angular, React and Vue examples here.

Verify email addresses independently

f you only want to verify email addresses without the CAPTCHA in the frontend, you do not need the widget. You can find more information at "Email Address Verification".

Add the Zencaptcha Widget to your Webpage​

To integrate the zencaptcha widget into a specific page of your website, such as the login page, registration page, contact page, newsletter page, etc., you need to add two small pieces of client-side code to render the captcha widget.

  1. Copy the first code snippet and paste the code snippet into the <head> section of your HTML code for the page where you want to display the widget. (It can also be placed immediately after the .zenc-captcha container - which you will add in point 2)
In your html:
<script src="https://www.zencaptcha.com/captcha/widget.js" onload="zencaptchaInit()" async defer></script>
  1. Copy the second code snippet and paste it into your HTML where you want the widget to appear. You can include the .zenc-captcha container in an HTML form or inside
    to benefit from functionalities like data-start="auto" or data-start="focus". When a captcha is successfully solved, a hidden token is automatically added to your form, which you need to POST to your server to be verified. You can retrieve it server-side with the POST parameter zenc-captcha-solution.
In your html:
<div class="zenc-captcha" data-sitekey="ADD-YOUR-SITEKEY-HERE"></div>
Don't forget this

Replace ADD-YOUR-SITEKEY-HERE from the snippet above with your own sitekey

Full (Simple) Frontend Example​

Here's a simple example of how Zencaptcha can be used to protect a registration form from abuse by automated spammers. When submitting the form, the zenc-captcha-solution token is included with the email and password POST data after solving the captcha. A complete suggested code example can be found at the bottom of this page.

<html>
  <head>
    <title>Zencaptcha Demo 1</title>
    <script src="https://www.zencaptcha.com/captcha/widget.js" onload="zencaptchaInit()" async defer></script>
  </head>
  <body>
    <form action="" method="POST">
      <input type="text" name="email" placeholder="Email" />
      <input type="password" name="password" placeholder="Password" />
      <div class="zenc-captcha" data-sitekey="ADD-YOUR-SITEKEY-HERE"></div>
      <br />
      <input type="submit" value="Submit" />
    </form>
  </body>
</html>

Solution Callback​

Best Practice

Prevent users from submitting the form by disabling the submit button until the CAPTCHA has been successfully completed. You can add data-callback="myCallback" to the zenc-captcha container. This will be called immediately and automatically when the captcha is completed.

`<div class="zenc-captcha" data-sitekey="ADD-YOUR-SITEKEY-HERE" data-callback="zenCallback"></div>`

and get the solution (token) in Javascript like this:

Javascript
function zenCallback(solution) {
    //here you must enable the submit button
    console.log("Captcha solution is" + solution);
    //now you could also send "solution" (the token) with the other user input to your backend
}

Getting The Captcha Response​

See the point "Starting, Resetting And Destroying The Widget" below. You can get the token (solution from the CAPTCHA) by the callback example above or just fetch it when you need it, like this:

Javascript
zencap.getResponse();
Other possible CAPTCHA values

There are 6 possible CAPTCHA values if the solution does not exist yet, if it expired, if it is loading or if there been another error: NOTSTARTED, INCONSISTENT, ERROR, LOADING, NOTFINISHED, EXPIRED. You can use that to only send the solution to your backend if the solution is none of these values. (See the code example Zencaptcha Demo 2 at the bottom of this page)

Starting, Resetting And Destroying The Widget​

If you want to start the widget programmatically or reset it, you should not forget to add onload="zencaptchaInit()" to the script tag.

Change your html:
<script src="https://www.zencaptcha.com/captcha/widget.js" onload="zencaptchaInit()" async defer></script>

In your javascript: You can start the widget automatically with zencap.start(); and reset it with zencap.reset();. You can also get the solution with zencap.getResponse();. You can destroy the widget with zencap.destroy();. Destroying the widget removes the widget and all DOM elements and terminates all running Zencaptcha processes.

Ideal Frontend Example​

Here's a complete ideal example of how to use Zencaptcha in the frontend by retrieving the solution from the CAPTCHA and only sending the solution and other data to the backend when the CAPTCHA has finished its verification process. In addition, the widget will be reset if it was checked on the server side and an error occurred. The user must then click on the widget again to prove that it is not a robot.

<!DOCTYPE html>
  <head>
    <title>Zencaptcha Demo 2</title>
    <script src="https://www.zencaptcha.com/captcha/widget.js" onload="zencaptchaInit()" async defer></script>
  </head>
<body>
  <h1>Login Form</h1>
  <form>
    <label for="email">Email:</label>
    <input type="email" id="email" required><br><br>
    <label for="password">Password:</label>
    <input type="password" id="password" required><br><br>
    <div class="zenc-captcha" data-sitekey="SITEKEY" data-callback="zenCallback"></div>
    <input type="button" value="Submit" onclick="sendData()">
  </form>
</body>
</html>
<script>
    function zenCallback(solution) {
        //Optional: You can make the Submit button clickable now - Alternatively, you can of course make the button clickable from the beginning and show the user a warning if no solution is found, as below in the sendData() function.
        // You can also capture the solution (token) as follows: let currenttoken = solution;
    }

    function sendData() {
      var email = document.getElementById("email").value;
      var password = document.getElementById("password").value;

      var zencaptchatoken = zencap.getResponse(); //retrieving the CAPTCHA solution
      if(zencaptchatoken=="NOTSTARTED" || zencaptchatoken=="NOTFINISHED" || zencaptchatoken=="EXPIRED" || zencaptchatoken=="INCONSISTENT" || zencaptchatoken=="ERROR" || zencaptchatoken=="LOADING"){
          //don't continue, as the token from the verification is not ready yet or the user did not yet complete the verification. You can show a warning here.
          alert("Verification not completed");
          return;
      }

      var data = {
        email: email,
        password: password,
        token: zencaptchatoken //send the Zencaptcha solution (token) to your backend
      };
      
      // Send the data with the token to your backend server where you need to do an API call to /siteverify (our server) to finally check the validity of the token
      fetch('http://your-backend-url.com/login', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
      })
      .then(function(response) {
        if (response.ok) {
          alert("Login successful!");
        } else {
          alert("Login failed!");
          zencap.reset(); //the widget is reset, so the user must run the verification again
        }
      })
      .catch(function(error) {
        console.log(error);
      });
    }
  </script>