ReCaptcha

by | May 12, 2025 | 0 comments

ViralMarketingWP – ReCaptcha Integration

Introduction

The ViralMarketingWP – ReCaptcha Integration addon provides powerful spam protection for your viral marketing campaigns by incorporating Google’s ReCaptcha technology. This integration helps ensure that only genuine participants can join your campaigns, protecting your data quality and preventing automated bot submissions.

Features

  • Dual ReCaptcha Support: Implement either ReCaptcha V2 (checkbox) or ReCaptcha V3 (invisible)
  • Easy Configuration: Simple setup with site and secret keys from Google
  • Seamless Integration: Automatically adds ReCaptcha to all campaign forms
  • Customizable Error Messages: Clear feedback for users when verification fails
  • IP Validation: Advanced security with proper IP address detection
  • Minimal Impact on UX: Options for visible or invisible verification

Requirements

  • WordPress 5.0 or higher
  • ViralMarketingWP plugin (core) installed and activated
  • Google ReCaptcha account with site and secret keys
  • PHP 7.0 or higher

Installation

  1. Download the ViralMarketingWP – ReCaptcha Integration addon from your account at viralmarketingwp.com
  2. Go to WordPress Admin > Plugins > Add New > Upload Plugin
  3. Choose the downloaded zip file and click Install Now
  4. After installation is complete, click Activate Plugin

Getting ReCaptcha Keys

Before configuring the plugin, you need to obtain ReCaptcha keys from Google:

  1. Visit the Google ReCaptcha Admin Console
  2. Sign in with your Google account
  3. Click the + button to create a new site registration
  4. Enter a label for your site (e.g., “My Viral Marketing Campaigns”)
  5. Choose the ReCaptcha type:
    • ReCaptcha v2 “I’m not a robot” Checkbox for visible verification
    • ReCaptcha v3 for invisible verification
  6. Add your domain(s) in the “Domains” field
  7. Accept the Terms of Service and click Submit
  8. You’ll receive two keys:
    • Site Key: Used in the frontend form
    • Secret Key: Used for backend verification

Configuration

Accessing ReCaptcha Settings

  1. Go to ViralMarketingWP > Settings in your WordPress admin
  2. Click on the Integrations tab
  3. Scroll down to find the Google ReCaptcha Integration section

Available Settings

  • Enable ReCaptcha: Turn ReCaptcha protection on or off for all campaign forms
  • ReCaptcha Version: Choose between ReCaptcha V2 (Checkbox) or ReCaptcha V3 (Invisible)
  • Site Key: Enter your ReCaptcha site key from Google
  • Secret Key: Enter your ReCaptcha secret key from Google

Setting Up ReCaptcha V2 (Checkbox)

ReCaptcha V2 displays a checkbox that users must click to verify they are human:

  1. Select ReCaptcha V2 (Checkbox) in the ReCaptcha Version dropdown
  2. Enter your V2 site key and secret key
  3. Save your settings
  4. A “I’m not a robot” checkbox will appear in all campaign forms

Setting Up ReCaptcha V3 (Invisible)

ReCaptcha V3 works invisibly in the background, scoring user interactions without requiring explicit verification:

  1. Select ReCaptcha V3 (Invisible) in the ReCaptcha Version dropdown
  2. Enter your V3 site key and secret key
  3. Save your settings
  4. ReCaptcha will work invisibly when users submit campaign forms

How ReCaptcha Works in Your Campaigns

ReCaptcha V2 (Checkbox)

  1. Users fill out your campaign form
  2. Before submitting, they must check the “I’m not a robot” box
  3. Google verifies the user based on their behavior and checkbox interaction
  4. If verification passes, the form is submitted
  5. If verification fails, an error message is displayed

ReCaptcha V3 (Invisible)

  1. Users fill out your campaign form
  2. When they click submit, ReCaptcha runs invisibly in the background
  3. Google analyzes the user’s behavior and assigns a score (0.0 to 1.0)
  4. If the score is above 0.5 (configurable threshold), the form is submitted
  5. If the score is below the threshold, the submission is blocked with an error message

Troubleshooting

ReCaptcha Not Appearing

If the ReCaptcha widget is not appearing on your forms:

  1. Verify that ReCaptcha is enabled in your settings
  2. Ensure you’ve entered valid site and secret keys
  3. Check that your site domain matches the domains you registered with Google
  4. Look for JavaScript errors in your browser console that might be preventing the ReCaptcha from loading
  5. Ensure your theme is not interfering with the form’s HTML structure

Form Submissions Being Blocked

If legitimate users are being blocked from submitting forms:

  1. For V2, make sure the ReCaptcha checkbox is visible and accessible
  2. For V3, consider that Google may be scoring some users too low – you might want to switch to V2 for better user control
  3. Check if users are on networks that Google might flag (VPNs, shared IPs, etc.)
  4. Verify that your secret key is correct and properly saved

Network Connection Issues

If you see errors related to ReCaptcha verification:

  1. Ensure your server can make outbound HTTP requests to Google’s verification servers
  2. Check if your server’s IP address is being rate-limited by Google
  3. Verify that any security plugins or firewalls are not blocking the verification requests

Technical Details

How Verification Works

The verification process follows these steps:

  1. When a form is submitted, the plugin captures the ReCaptcha response token
  2. The plugin sends this token to Google’s verification API along with your secret key
  3. Google returns a verification result, including success status and (for V3) a score
  4. The plugin evaluates the result and either allows or blocks the submission

IP Address Detection

The plugin uses a sophisticated method to detect the visitor’s IP address:

  1. Checks HTTP_CLIENT_IP header (if available)
  2. Checks HTTP_X_FORWARDED_FOR header (if available)
  3. Falls back to REMOTE_ADDR
  4. Validates the IP format for security

Error Handling

When ReCaptcha verification fails:

  1. Custom error messages are displayed to users
  2. Error details are logged (when WP_DEBUG is enabled)
  3. The form submission is prevented
  4. Special handling is applied for certain cases (e.g., emails with ‘+’ symbols)

Best Practices

Choosing Between V2 and V3

  • Use V2 (Checkbox) when:
    • You want users to be explicitly aware of the verification
    • Your audience may include users who could be incorrectly scored by V3
    • You prefer an obviously visible security measure
  • Use V3 (Invisible) when:
    • You want a frictionless user experience
    • Your forms are on high-traffic pages
    • You’re willing to accept some false positives for greater convenience

Optimizing Your Forms

  1. Position matters: If using V2, place the ReCaptcha widget in a visible location
  2. Clear instructions: Let users know verification is required
  3. Mobile-friendly design: Ensure your forms work well on all devices
  4. Error messages: Customize error messages to be helpful and clear

Updates

This plugin receives regular updates to ensure compatibility with the latest versions of WordPress, ViralMarketingWP, and Google ReCaptcha. Keep your plugin updated to ensure optimal functionality and security.