reCAPTCHA v3 Integration

Implement invisible reCAPTCHA v3 protection with advanced score-based spam detection.

Overview

reCAPTCHA v3 provides invisible spam protection by analyzing user behavior and returning a risk score (0.0-1.0) without disrupting the user experience. Unlike v2, users never see a challenge or checkbox.

✨ Key Benefits

Invisible protection - no user interaction required
Score-based analysis (0.0 = likely bot, 1.0 = likely human)
Action-based verification for better context
Configurable thresholds and security levels

Setup Process

Get reCAPTCHA v3 API Keys

Visit the Google reCAPTCHA Admin Console and:

Create a new site
Select "reCAPTCHA v3"
Add your domains (including localhost for testing)
Copy your Site Key and Secret Key

Add reCAPTCHA to Your Form

Add the reCAPTCHA v3 library to your page and implement the verification:

<!DOCTYPE html>
<html>
<head>
  <!-- Add reCAPTCHA v3 script -->
  <script src="https://www.google.com/recaptcha/api.js"></script>
</head>
<body>
  <form id="contact-form" action="https://connect.kitoform.com/f/YOUR_ENDPOINT" method="POST">
    <input type="text" name="name" placeholder="Your Name" required />
    <input type="email" name="email" placeholder="Your Email" required />
    <textarea name="message" placeholder="Your Message" required></textarea>
    
    <!-- Hidden field for reCAPTCHA token -->
    <input type="hidden" name="g-recaptcha-response" id="g-recaptcha-response" />
    
    <button type="submit">Send Message</button>
  </form>

  <script>
    // Initialize reCAPTCHA when page loads
    grecaptcha.ready(function() {
      // Execute reCAPTCHA on form submission
      document.getElementById('contact-form').addEventListener('submit', function(e) {
        e.preventDefault();
        
        grecaptcha.execute('YOUR_SITE_KEY', {action: 'submit_form'}).then(function(token) {
          // Add token to form
          document.getElementById('g-recaptcha-response').value = token;
          
          // Submit the form
          document.getElementById('contact-form').submit();
        });
      });
    });
  </script>
</body>
</html>

React Implementation

For React applications, you can use the react-google-recaptcha library or implement it manually:

import { useEffect, useRef } from 'react';

const ContactForm = () => {
  const formRef = useRef();
  const recaptchaRef = useRef();

  useEffect(() => {
    // Load reCAPTCHA script
    const script = document.createElement('script');
    script.src = 'https://www.google.com/recaptcha/api.js';
    script.async = true;
    document.head.appendChild(script);
    
    return () => {
      document.head.removeChild(script);
    };
  }, []);

  const handleSubmit = async (e) => {
    e.preventDefault();
    
    if (window.grecaptcha) {
      try {
        const token = await window.grecaptcha.execute('YOUR_SITE_KEY', {
          action: 'submit_form'
        });
        
        // Add token to form data
        const formData = new FormData(formRef.current);
        formData.append('g-recaptcha-response', token);
        
        // Submit to Kitoform
        const response = await fetch('https://connect.kitoform.com/f/YOUR_ENDPOINT', {
          method: 'POST',
          body: formData
        });
        
        if (response.ok) {
          alert('Form submitted successfully!');
        }
      } catch (error) {
        console.error('reCAPTCHA error:', error);
      }
    }
  };

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      <input type="text" name="name" placeholder="Your Name" required />
      <input type="email" name="email" placeholder="Your Email" required />
      <textarea name="message" placeholder="Your Message" required />
      <button type="submit">Send Message</button>
    </form>
  );
};

export default ContactForm;

Configure Kitoform Settings

Configure reCAPTCHA v3 settings in your Kitoform dashboard or via API:

{
  "settings": {
    "captchaProvider": "recaptcha",
    "recaptchaEnabled": true,
    "recaptchaVersion": "v3",
    "recaptchaSiteKey": "6Lc-your-site-key",
    "recaptchaSecretKey": "6Lc-your-secret-key",
    "recaptchaThreshold": 0.5,
    "recaptchaAction": "submit_form",
    "securityLevel": "standard"
  }
}

Security Note: Store your Secret Key securely in Kitoform. Never expose it in frontend code.

Configuration Options

Setting	Type	Default	Description
recaptchaThreshold	number	0.5	Minimum score to pass (0.0-1.0)
recaptchaAction	string	submit_form	Action name for verification context
securityLevel	enum	standard	standard, strict, or paranoid
recaptchaExpectedHostname	string	null	Expected hostname for additional security

Security Levels

Kitoform provides three security levels that combine reCAPTCHA scores with additional spam factors:

🟢 Standard

Block at 70+ spam score
Flag at 40+ spam score
Recommended for most websites
Good balance of security and usability

🟡 Strict

Block at 50+ spam score
Flag at 25+ spam score
Higher security, some false positives
Good for high-value forms

🔴 Paranoid

Block at 30+ spam score
Flag at 15+ spam score
Maximum security
May block legitimate users

Score Interpretation

reCAPTCHA v3 returns a score between 0.0 and 1.0. Here's how to interpret the scores:

0.0-0.1

Very likely bot

Automated behavior detected, high confidence

0.1-0.3

Likely bot

Suspicious patterns, likely automated

0.3-0.7

Uncertain

Mixed signals, requires additional analysis

0.7-1.0

Likely human

Human-like behavior patterns detected

Testing Your Implementation

Development Testing

During development, you can test with localhost domains. Make sure to add localhostand 127.0.0.1 to your reCAPTCHA domain list.

Test domains to add:

localhost
127.0.0.1
your-development-domain.com

Monitoring and Analytics

Monitor your reCAPTCHA performance through:

Kitoform dashboard spam analytics
Google reCAPTCHA Admin Console
Form submission success rates

Common Issues

ERROR: Invalid site key

Make sure your Site Key is correct and the domain is registered in reCAPTCHA console.

Check: Site Key, domain whitelist, reCAPTCHA version (v3)

ERROR: Invalid response token

The reCAPTCHA token is invalid, expired, or used before.

Check: Token generation, form submission timing, duplicate submissions

Low scores on legitimate traffic

Consider lowering your threshold or switching to "standard" security level.

Recommended: Start with 0.5 threshold and adjust based on your traffic patterns