FormProtect Widget Documentation

🚀 Quick Start

Get FormProtect running on your website in under 5 minutes:

1. Include the Widget Script

<script src="https://forms.blunek.services/widget.js"></script>

2. Add Data Attributes to Your Form

                <form data-formprotect-key="fp_your_api_key_here">
    <input type="text" name="name" placeholder="Name" required>
    <input type="email" name="email" placeholder="Email" required>
    <textarea name="message" placeholder="Message" required></textarea>
    <button type="submit">Submit</button>
</form>
            

That's it! FormProtect will automatically protect your form against spam while maintaining a smooth user experience.

📦 Installation Methods

Method 1: CDN (Recommended)

Include the widget directly from our CDN:

<script src="https://forms.blunek.services/widget.js"></script>

Method 2: Download and Host

Download widget.js and host it on your server:

<script src="/path/to/your/widget.js"></script>

Method 3: Manual Initialization

                <script src="https://forms.blunek.services/widget.js"></script>
<script>
    const formProtect = new FormProtect('your_api_key', {
        debug: true,
        onValidation: function(isValid, result) {
            console.log('Validation result:', isValid, result);
        }
    });
    formProtect.attachToForm('#my-form');
</script>
            

⚙️ Configuration Options

Data Attributes (Auto-initialization)

Attribute	Description	Default	Example
`data-formprotect-key`	Your API key (required)	-	`fp_abc123...`
`data-formprotect-honeypot`	Honeypot field name	`hp_field`	`honeypot`
`data-formprotect-challenge-container`	Challenge container selector	Auto-created	`#challenge-div`
`data-formprotect-debug`	Enable debug logging	`false`	`true`

JavaScript Options (Manual initialization)

                const formProtect = new FormProtect('your_api_key', {
    honeypotField: 'hp_field',        // Honeypot field name
    challengeContainer: '#challenge', // Challenge container selector
    debug: false,                     // Enable debug mode
    
    // Callback functions
    onValidation: function(isValid, result) {
        // Called after validation
        if (isValid) {
            console.log('Form is valid!');
        } else {
            console.log('Validation failed:', result.reasons);
        }
    },
    
    onChallenge: function(challenge) {
        // Called when challenge is shown
        console.log('Challenge required:', challenge.question);
    }
});
            

🔌 API Reference

FormProtect Class

Constructor

new FormProtect(apiKey, options)

Parameters:

apiKey (string): Your FormProtect API key
options (object): Configuration options

Methods

`attachToForm(selector)`

Attach FormProtect to a form element.

                formProtect.attachToForm('#my-form');
formProtect.attachToForm('.contact-form');
            

`validateForm(formElement, challengeAnswer)`

Manually trigger form validation.

                const form = document.querySelector('#my-form');
await formProtect.validateForm(form);
            

API Endpoints

POST /api/validate

Validate a form submission.

Request Body:

                {
    "api_key": "fp_your_api_key",
    "form_data": {
        "name": "John Doe",
        "email": "john@example.com",
        "message": "Hello world!"
    },
    "honeypot_field": "hp_field",
    "submission_time": 1645123456.789,
    "fingerprint": "{...browser_fingerprint...}",
    "challenge_id": "optional_challenge_id",
    "challenge_answer": "optional_challenge_answer"
}
            

Response:

                {
    "valid": true,
    "score": 95,
    "reasons": ["Legitimate user behavior detected"],
    "challenge": null
}
            

GET /api/usage/{api_key}

Get usage statistics for your API key.

GET /api/analytics/{api_key}

Get detailed analytics and spam detection insights.

💡 Examples

Basic Contact Form

                <!DOCTYPE html>
<html>
<head>
    <title>Contact Form</title>
</head>
<body>
    <form data-formprotect-key="fp_your_api_key" action="/submit" method="POST">
        <label for="name">Name:</label>
        <input type="text" id="name" name="name" required>
        
        <label for="email">Email:</label>
        <input type="email" id="email" name="email" required>
        
        <label for="message">Message:</label>
        <textarea id="message" name="message" required></textarea>
        
        <button type="submit">Send Message</button>
    </form>
    
    <script src="https://forms.blunek.services/widget.js"></script>
</body>
</html>
            

Advanced Configuration

                <form id="advanced-form">
    <!-- Your form fields -->
</form>

<div id="custom-challenge" style="display: none;">
    <!-- Custom challenge container -->
</div>

<script>
    const formProtect = new FormProtect('fp_your_api_key', {
        honeypotField: 'custom_honeypot',
        challengeContainer: '#custom-challenge',
        debug: true,
        
        onValidation: function(isValid, result) {
            if (isValid) {
                showSuccessMessage('Form submitted successfully!');
            } else {
                showErrorMessage('Spam detected: ' + result.reasons.join(', '));
            }
        },
        
        onChallenge: function(challenge) {
            document.getElementById('custom-challenge').style.display = 'block';
            // Custom challenge UI logic
        }
    });
    
    formProtect.attachToForm('#advanced-form');
</script>
            

Multiple Forms on Same Page

                <!-- Contact Form -->
<form data-formprotect-key="fp_your_api_key" data-formprotect-honeypot="contact_hp">
    <!-- contact form fields -->
</form>

<!-- Newsletter Form -->
<form data-formprotect-key="fp_your_api_key" data-formprotect-honeypot="newsletter_hp">
    <!-- newsletter form fields -->
</form>

<script src="https://forms.blunek.services/widget.js"></script>
            

Custom Styling

                <style>
    .formprotect-challenge {
        border: 2px solid #007bff;
        border-radius: 8px;
        padding: 20px;
        background: #f8f9fa;
        margin: 15px 0;
    }
    
    .formprotect-challenge h4 {
        color: #007bff;
        margin-bottom: 10px;
    }
    
    .formprotect-challenge input {
        padding: 10px;
        border: 1px solid #ced4da;
        border-radius: 4px;
        margin-right: 10px;
    }
    
    .formprotect-challenge button {
        padding: 10px 20px;
        background: #007bff;
        color: white;
        border: none;
        border-radius: 4px;
        cursor: pointer;
    }
</style>
            

🔧 Troubleshooting

Common Issues

⚠️ "Invalid API key" Error

Verify your API key is correct and properly formatted
Check that you haven't exceeded your monthly limit
Ensure the API key is active (not disabled)

⚠️ Forms Not Being Protected

Verify the widget script is loaded before the form
Check that the data-formprotect-key attribute is present
Enable debug mode to see console messages
Ensure your form has a proper submit button (not just JavaScript submission)

⚠️ Challenge Not Appearing

Check that your challenge container selector is valid
Ensure CSS doesn't hide the challenge container
Try using the default challenge container (auto-created)

Debug Mode

Enable debug mode to see detailed logging:

                <form data-formprotect-key="fp_your_key" data-formprotect-debug="true">
    <!-- form fields -->
</form>
            

Or with JavaScript:

                const formProtect = new FormProtect('fp_your_key', {
    debug: true
});
            

Testing Your Integration

💡 Testing Tips

Test with both valid and suspicious form data
Try submitting forms very quickly to trigger time-based detection
Fill honeypot fields to test bot detection
Monitor your analytics dashboard for insights

Browser Compatibility

FormProtect supports:

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+
iOS Safari 12+
Android Chrome 60+

Need Help?

Still having issues? We're here to help!

📧 Email: support@blunek.services
📊 Check your analytics dashboard
🔍 Use debug mode for detailed logging

🛡️ FormProtect Widget