Enabling reCAPTCHA for Forms

Forge supports Google reCAPTCHA integration to protect your forms from spam, bots, and automated abuse. reCAPTCHA uses advanced risk analysis to distinguish between legitimate users and automated software, helping to keep your forms secure while maintaining a smooth user experience.

What is reCAPTCHA?

reCAPTCHA is Google's free service that protects websites from spam and abuse. It uses an adaptive risk analysis engine to evaluate whether a user is human or a bot, and can present challenges when suspicious activity is detected.

Benefits of reCAPTCHA

• Spam Protection: Prevents automated bots from submitting forms
• Account Takeover Prevention: Protects against credential stuffing attacks
• Fraud Prevention: Helps identify and block fraudulent transactions
• Frictionless Experience: Most legitimate users won't see challenges
• Privacy Preserving: Data is used only for security purposes, not advertising

Setting Up reCAPTCHA

Step 1: Get reCAPTCHA Keys

1. Go to the reCAPTCHA Admin Console
2. Click "Create" to register a new site
3. Choose "reCAPTCHA v2" and select "I'm not a robot" Checkbox
4. Add your domain(s) to the "Domains" section
5. Accept the terms of service and click "Submit"
6. Copy your Site Key and Secret Key

Step 2: Configure reCAPTCHA in Forge

Once you have your reCAPTCHA keys, you can enable reCAPTCHA for your forms in the Forge dashboard:

1. Navigate to your site in the Forge dashboard
2. Go to the "Forms" tab
3. Select the form you want to protect with reCAPTCHA
4. Click on "Settings" or "Configure"
5. Find the "reCAPTCHA" section
6. Enable reCAPTCHA by toggling the switch
7. Enter your reCAPTCHA Site Key in the provided field
8. Enter your reCAPTCHA Secret Key in the provided field
9. Save your changes

Step 3: Add reCAPTCHA to Your Form

After configuring reCAPTCHA in the Forge dashboard, you need to add the reCAPTCHA widget to your form HTML:

Option 1: Automatic Integration (Recommended)

Forge can automatically inject the reCAPTCHA widget into your forms. Simply add the data-forge-recaptcha attribute to your form:

<form data-forge-name="Contact Form" data-forge-recaptcha="true">
  <input type="text" data-forge-name="Name" placeholder="Your Name" required>
  <input type="email" data-forge-name="Email" placeholder="Your Email" required>
  <textarea data-forge-name="Message" placeholder="Your Message" required></textarea>
  <button type="submit">Send Message</button>
</form>

Option 2: Manual Integration

If you prefer to manually control the reCAPTCHA placement, you can add it yourself:

<form data-forge-name="Contact Form">
  <input type="text" data-forge-name="Name" placeholder="Your Name" required>
  <input type="email" data-forge-name="Email" placeholder="Your Email" required>
  <textarea data-forge-name="Message" placeholder="Your Message" required></textarea>
  
  <!-- Add reCAPTCHA widget -->
  <div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
  
  <button type="submit">Send Message</button>
</form>

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

reCAPTCHA Configuration Options

Theme Options

You can customize the appearance of the reCAPTCHA widget by adding the data-theme attribute:

<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY" data-theme="dark"></div>

Available themes:

• light - Default light theme
• dark - Dark theme

Size Options

Control the size of the reCAPTCHA widget:

<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY" data-size="compact"></div>

Available sizes:

• normal - Default size
• compact - Smaller size
• invisible - Hidden widget (requires custom implementation)

Testing reCAPTCHA

To test your reCAPTCHA integration:

1. Deploy your site with the reCAPTCHA-enabled form
2. Visit your form page
3. You should see the reCAPTCHA widget (usually a checkbox with "I'm not a robot")
4. Try submitting the form without completing the reCAPTCHA - it should be blocked
5. Complete the reCAPTCHA and submit the form - it should work normally

Best Practices

User Experience

• Placement: Position the reCAPTCHA widget near the submit button for better UX
• Clear Instructions: Consider adding a brief explanation of why reCAPTCHA is needed
• Accessibility: Ensure your form remains accessible to users with disabilities

Security

• Keep Keys Secure: Never expose your secret key in client-side code
• Domain Validation: Only add domains you control to the reCAPTCHA admin console
• Regular Monitoring: Check your reCAPTCHA analytics for unusual patterns

Performance

• Lazy Loading: Consider loading reCAPTCHA only when needed
• CDN Usage: reCAPTCHA scripts are served from Google's CDN for optimal performance

Troubleshooting

Common Issues

reCAPTCHA Not Appearing

• Check that your site key is correct
• Verify your domain is added to the reCAPTCHA admin console
• Ensure the reCAPTCHA script is loading properly

Form Submissions Blocked

• Verify your secret key is correct in the Forge dashboard
• Check that reCAPTCHA is properly configured for the form
• Test with a different browser or device

reCAPTCHA Challenges Too Frequent

• This may indicate suspicious activity from your IP or network
• Consider adjusting reCAPTCHA sensitivity settings
• Check if you're using a VPN or proxy service

Advanced Configuration

Custom Styling

You can customize the appearance of the reCAPTCHA widget using CSS:

<style>
.g-recaptcha {
  margin: 20px 0;
  transform: scale(0.9);
  transform-origin: 0 0;
}

/* Dark theme adjustments */
.g-recaptcha[data-theme="dark"] {
  filter: invert(1);
}
</style>

Callback Functions

For advanced use cases, you can use reCAPTCHA callback functions:

<div class="g-recaptcha" 
     data-sitekey="YOUR_SITE_KEY" 
     data-callback="onRecaptchaSuccess" 
     data-expired-callback="onRecaptchaExpired"></div>

<script>
function onRecaptchaSuccess(token) {
  console.log('reCAPTCHA completed successfully');
  // Enable submit button or proceed with form submission
}

function onRecaptchaExpired() {
  console.log('reCAPTCHA expired');
  // Handle expired reCAPTCHA
}
</script>

Monitoring and Analytics

reCAPTCHA provides analytics and monitoring through the Google reCAPTCHA admin console:

• Success Rate: Monitor how often users successfully complete reCAPTCHA
• Challenge Rate: Track how frequently challenges are presented
• Error Rates: Identify any issues with reCAPTCHA implementation
• Geographic Data: View reCAPTCHA usage by location

By following this guide, you can effectively protect your Forge forms with reCAPTCHA while maintaining a good user experience. The combination of Forge's form hosting and reCAPTCHA's bot protection provides a robust solution for handling form submissions securely.