Overview
reCAPTCHA lock protects downloads from bots and automated abuse by requiring human verification. Using Google’s reCAPTCHA service, it distinguishes humans from bots while providing a seamless experience for legitimate users.
Prerequisites
- WordPress Download Manager installed
- Google reCAPTCHA site keys
- At least one published package
Quick Start
- Get reCAPTCHA keys from Google
- Enter keys at Downloads > Settings > Security
- Edit a package
- Enable reCAPTCHA Lock
- Save package
Getting reCAPTCHA Keys
Step 1: Register Site
- Go to google.com/recaptcha/admin
- Sign in with Google account
- Click + Create or Add new site
Step 2: Configure
| Field | Value |
|---|---|
| Label | Your site name |
| reCAPTCHA Type | Choose v2 or v3 |
| Domains | yourdomain.com |
Step 3: Get Keys
After registering, you’ll receive:
- Site Key (public)
- Secret Key (private)
Copy both keys.
Step 4: Enter in WPDM
- Go to Downloads > Settings > Security
- Find reCAPTCHA Settings
- Enter Site Key
- Enter Secret Key
- Save settings
reCAPTCHA Versions
reCAPTCHA v2 (Checkbox)
“I’m not a robot” checkbox:
┌─────────────────────────────────────┐ │ │ │ ┌─────────────────────────────┐ │ │ │ ☐ I'm not a robot │ │ │ │ [reCAPTCHA logo] │ │ │ └─────────────────────────────┘ │ │ │ │ [Download] │ │ │ └─────────────────────────────────────┘
Pros:
- Clear user interaction
- High accuracy
- Works without cookies
Cons:
- Visible extra step
- May trigger image challenges
reCAPTCHA v2 Invisible
No checkbox, automatic verification:
┌─────────────────────────────────────┐ │ │ │ [Download] │ │ │ │ Protected by reCAPTCHA │ │ │ └─────────────────────────────────────┘
Verification happens when clicking download.
Pros:
- Seamless for most users
- No visible checkbox
- Same security level
Cons:
- May show challenge for suspicious behavior
- Requires JavaScript
reCAPTCHA v3
Score-based, invisible verification:
No visible element Runs in background Returns risk score (0.0 - 1.0)
Pros:
- Completely invisible
- No user interaction
- Continuous protection
Cons:
- May have false positives
- Requires score threshold tuning
Enabling reCAPTCHA Lock
Per-Package
- Edit a package
- Find Lock Options panel
- Enable reCAPTCHA Lock
- Save package
All Packages
At Downloads > Settings > Security:
☑ Enable reCAPTCHA for all packages
Configuration Options
Settings
| Option | Description |
|---|---|
| reCAPTCHA Version | v2 Checkbox, v2 Invisible, or v3 |
| Site Key | Your public key |
| Secret Key | Your private key |
| Theme | Light or Dark |
| Size | Normal or Compact |
| Score Threshold | For v3 (0.0-1.0, default 0.5) |
Theme Options
Light Theme:
Background: White Text: Dark gray Border: Light gray
Dark Theme:
Background: Dark gray Text: White Border: Medium gray
Size Options
Normal:
- Standard size
- Best for most layouts
Compact:
- Smaller footprint
- For tight spaces
User Experience
v2 Checkbox Flow
- User clicks download
- reCAPTCHA appears
- User checks “I’m not a robot”
- If suspicious: Image challenge appears
- On success: Download starts
v2 Invisible Flow
- User clicks download
- Background verification
- If human: Download starts immediately
- If suspicious: Challenge popup appears
v3 Flow
- User loads page (verification starts)
- User clicks download
- Score evaluated
- If score >= threshold: Download starts
- If score < threshold: Fallback or block
Combining with Other Locks
reCAPTCHA + Email
Collect email with bot protection:
Locks: ☑ Email Lock ☑ reCAPTCHA Lock
User completes both before download.
reCAPTCHA + Password
Password entry with bot protection:
Locks: ☑ Password Lock ☑ reCAPTCHA Lock
Prevents brute-force password attempts.
Advanced Configuration
Custom Threshold (v3)
// Set custom score threshold
add_filter('wpdm_recaptcha_threshold', function($threshold) {
return 0.7; // Stricter (default 0.5)
});
Custom Error Message
add_filter('wpdm_recaptcha_error', function($message) {
return 'Verification failed. Please try again or contact support.';
});
Bypass for Logged-in Users
add_filter('wpdm_skip_recaptcha', function($skip, $package_id) {
if (is_user_logged_in()) {
return true; // Skip for logged-in users
}
return $skip;
}, 10, 2);
Troubleshooting
“Invalid Site Key”
Causes:
- Typo in site key
- Key from different Google account
- Domain mismatch
Solutions:
- Copy key directly from reCAPTCHA admin
- Verify domain is registered
- Regenerate keys if needed
reCAPTCHA Not Appearing
Causes:
- JavaScript error
- Keys not configured
- Lock not enabled
Solutions:
- Check browser console
- Verify keys are entered
- Confirm lock is enabled for package
Always Showing Challenge
Causes:
- VPN/proxy detected
- Browser fingerprint suspicious
- Testing from same IP repeatedly
Solutions:
- Normal behavior for suspicious traffic
- Different IPs for testing
- Use test keys for development
v3 Blocking Legitimate Users
Cause: Threshold too high
Solution:
- Lower threshold (try 0.3-0.4)
- Implement fallback to v2
- Log scores to analyze
Test Keys for Development
Google provides test keys that always pass:
| Key Type | Value |
|---|---|
| Site Key | 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI |
| Secret Key | 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe |
Note: Only use for development. Switch to real keys for production.
Privacy Considerations
Data Collection
Google reCAPTCHA collects:
- IP address
- Browser information
- Mouse movements
- Time on page
Privacy Policy
Update your privacy policy to mention:
- Use of Google reCAPTCHA
- Data shared with Google
- Purpose of verification
GDPR Compliance
For EU users:
- Disclose reCAPTCHA in cookie policy
- Consider consent before loading
- Provide alternative if required
Related Documentation
Last updated: January 2026
Applies to: WordPress Download Manager 7.x