| 1 |
# Cloudflare Turnstile Field - User Guide |
| 2 |
|
| 3 |
## Overview |
| 4 |
|
| 5 |
Contact Forms by Cimatti now includes native support for Cloudflare Turnstile, a modern CAPTCHA alternative that provides bot protection without frustrating user experiences. |
| 6 |
|
| 7 |
**Version Added:** 1.9.14 |
| 8 |
|
| 9 |
## How It Works |
| 10 |
|
| 11 |
Unlike traditional CAPTCHA integrations that automatically appear on all forms, the Turnstile field uses a **field-based approach**: |
| 12 |
|
| 13 |
- � |
| 14 |
Appears as a draggable field in the form builder |
| 15 |
- � |
| 16 |
You control which forms use Turnstile |
| 17 |
- � |
| 18 |
You control where the Turnstile widget appears |
| 19 |
- � |
| 20 |
Existing forms remain unchanged |
| 21 |
|
| 22 |
## Quick Start |
| 23 |
|
| 24 |
### 1. Install Simple Cloudflare Turnstile (Required) |
| 25 |
|
| 26 |
The Turnstile field requires the [](https://it.wordpress.org/plugins/simple-cloudflare-turnstile/Simple Cloudflare Turnstile](https://it.wordpress.org/plugins/simple-cloudflare-turnstile/](https://it.wordpress.org/plugins/simple-cloudflare-turnstile/) plugin to function: |
| 27 |
|
| 28 |
1. Go to **Plugins → Add New** |
| 29 |
2. Search for "Simple Cloudflare Turnstile" |
| 30 |
3. Install and activate |
| 31 |
|
| 32 |
### 2. Configure Your Cloudflare Keys |
| 33 |
|
| 34 |
1. Get your keys from [](https://dash.cloudflare.com/Cloudflare Dashboard](https://dash.cloudflare.com/](https://dash.cloudflare.com/) |
| 35 |
2. Go to **Settings → Cloudflare Turnstile** |
| 36 |
3. Enter your **Site Key** and **Secret Key** |
| 37 |
4. Save settings |
| 38 |
|
| 39 |
### 3. Add Turnstile to Your Form |
| 40 |
|
| 41 |
1. Go to **Forms → Edit Form** |
| 42 |
2. Find **Turnstile** in the Fields sidebar |
| 43 |
3. **Drag it** into your form (typically before the Submit button) |
| 44 |
4. Save your form |
| 45 |
|
| 46 |
That's it! The Turnstile widget will now appear when users view your form. |
| 47 |
|
| 48 |
## Widget Appearance |
| 49 |
|
| 50 |
The Turnstile widget appears as a checkbox-style verification: |
| 51 |
- Shows Cloudflare branding |
| 52 |
- Displays a green checkmark when completed |
| 53 |
- Automatically resets after form submission |
| 54 |
- Works in all modern browsers |
| 55 |
|
| 56 |
## Configuration Options |
| 57 |
|
| 58 |
The Turnstile field uses these default settings: |
| 59 |
|
| 60 |
- **Theme:** Auto (matches user's browser preference) |
| 61 |
- **Language:** Auto-detected from browser |
| 62 |
- **Size:** Normal |
| 63 |
- **Appearance:** Always visible |
| 64 |
|
| 65 |
These settings work well for most use cases. Future versions may include customization options. |
| 66 |
|
| 67 |
## Testing |
| 68 |
|
| 69 |
For testing purposes, you can use Cloudflare's test keys: |
| 70 |
|
| 71 |
- **Site Key:** `1x00000000000000000000AA` |
| 72 |
- **Secret Key:** `1x0000000000000000000000000000000AA` |
| 73 |
|
| 74 |
Test keys always show a success state, which is perfect for development and testing. |
| 75 |
|
| 76 |
## Validation |
| 77 |
|
| 78 |
The Turnstile field validates server-side, meaning: |
| 79 |
|
| 80 |
- � |
| 81 |
Users cannot bypass it by disabling JavaScript (validation happens on the server) |
| 82 |
- � |
| 83 |
Bot protection is maintained even with creative bypass attempts |
| 84 |
- � |
| 85 |
Integrates seamlessly with Contact Forms' existing validation system |
| 86 |
|
| 87 |
## Privacy & Performance |
| 88 |
|
| 89 |
Cloudflare Turnstile is designed with privacy in mind: |
| 90 |
|
| 91 |
- No personal data collection |
| 92 |
- No cookies required |
| 93 |
- Minimal impact on page load time |
| 94 |
- Compliant with privacy regulations (GDPR, etc.) |
| 95 |
|
| 96 |
## Troubleshooting |
| 97 |
|
| 98 |
### Widget doesn't appear |
| 99 |
|
| 100 |
1. Check that Simple Cloudflare Turnstile plugin is installed and activated |
| 101 |
2. Verify Cloudflare Turnstile keys are configured in Settings → Cloudflare Turnstile |
| 102 |
3. Check that Turnstile field is added to the form |
| 103 |
4. Clear browser cache |
| 104 |
5. Check browser console for JavaScript errors |
| 105 |
|
| 106 |
### "Plugin Required" or "Configuration Required" message |
| 107 |
|
| 108 |
If you see "Plugin Required": |
| 109 |
1. Install Simple Cloudflare Turnstile plugin from https://it.wordpress.org/plugins/simple-cloudflare-turnstile/ |
| 110 |
2. Activate the plugin |
| 111 |
3. Refresh the form page |
| 112 |
|
| 113 |
If you see "Configuration Required": |
| 114 |
1. Go to Settings → Cloudflare Turnstile |
| 115 |
2. Configure your Site Key and Secret Key |
| 116 |
3. Refresh the form page |
| 117 |
|
| 118 |
### Form submission fails |
| 119 |
|
| 120 |
1. Check that Cloudflare Turnstile service is working (check Cloudflare status) |
| 121 |
2. Verify your Secret Key is correct |
| 122 |
3. Check that your domain is authorized in Cloudflare Dashboard |
| 123 |
4. Look for validation errors in the form |
| 124 |
|
| 125 |
## For Developers |
| 126 |
|
| 127 |
### Architecture |
| 128 |
|
| 129 |
The Turnstile field follows Contact Forms' standard architecture: |
| 130 |
|
| 131 |
- **Element Class:** `AccuaForm_Element_Turnstile` (`/classes/Element/Turnstile.php`) |
| 132 |
- **Validation Class:** `AccuaForm_Validation_Turnstile` (`/classes/Validation/Turnstile.php`) |
| 133 |
|
| 134 |
### Customization Hooks |
| 135 |
|
| 136 |
Future versions may include WordPress filters for customization. Current version focuses on working out-of-the-box with sensible defaults. |
| 137 |
|
| 138 |
### API Integration |
| 139 |
|
| 140 |
The validation class uses these methods (in order of preference): |
| 141 |
|
| 142 |
1. `cfturnstile_check()` - From Simple Cloudflare Turnstile plugin |
| 143 |
2. `wp_remote_post()` - Direct Cloudflare API call |
| 144 |
3. `curl` - Fallback if wp_remote_post fails |
| 145 |
|
| 146 |
This ensures maximum compatibility across different WordPress configurations. |
| 147 |
|
| 148 |
## Support |
| 149 |
|
| 150 |
For issues specific to: |
| 151 |
|
| 152 |
- **Turnstile Field:** Contact [](https://www.cimatti.it/en/wordpress-plugins/contact-forms/Cimatti](https://www.cimatti.it/en/wordpress-plugins/contact-forms/](https://www.cimatti.it/en/wordpress-plugins/contact-forms/) |
| 153 |
- **Cloudflare Turnstile Plugin:** Visit [](https://wordpress.org/support/plugin/simple-cloudflare-turnstile/WordPress Support](https://wordpress.org/support/plugin/simple-cloudflare-turnstile/](https://wordpress.org/support/plugin/simple-cloudflare-turnstile/) |
| 154 |
- **Cloudflare Service:** Check [](https://developers.cloudflare.com/turnstile/Cloudflare Documentation](https://developers.cloudflare.com/turnstile/](https://developers.cloudflare.com/turnstile/) |
| 155 |
|
| 156 |
## Changelog |
| 157 |
|
| 158 |
### Version 1.9.14 (2025-01-24) |
| 159 |
|
| 160 |
- Initial release of Turnstile field integration |
| 161 |
- Field-based approach (drag-and-drop) |
| 162 |
- Works standalone or with Simple Cloudflare Turnstile plugin |
| 163 |
- Server-side validation with multiple fallbacks |
| 164 |
- Auto-reset after AJAX submissions |
| 165 |
- Backward compatible with existing forms |
| 166 |
|
