Seatext library / BotRefund evidence
How to Set Up a Bot Detection Script for Your Site
Start with checking for JavaScript support, setting event listeners, and recording timing patterns. Combine those signals into a scoring system, then add honeypot traps and edge-case handling. Verify with a simple test before deploying.
✓ Built for advertisers who need clear, refund-ready traffic evidence.
To set up a bot detection script, start by checking whether the visitor's browser supports JavaScript, then attach event listeners for mouse, keyboard, scroll, and touch, and record timing patterns like input speed and page dwell time. Combine these signals into a score, and only block when the score is high and corroborated by other checks.
This guide walks through the full configuration process, from prerequisites to testing. You'll build a basic script that can distinguish most automated browsers from real people without over-blocking genuine users.
Before You Start: Readiness Checklist
Have these items ready before you write any code:
- A clear policy on what you'll do with detected bots (block, challenge, or just log).
- Access to your site's HTML to insert the script in the
<head>. - Basic knowledge of JavaScript and browser developer tools.
- A test environment where you can simulate both real users and bots.
- Decide whether you'll use a self-built script or a commercial service. This guide covers the self-built route.
Step 1: Check JavaScript Support and Browser APIs
Start with the simplest signal: does the client even run JavaScript? Most modern bots use headless browsers that execute JavaScript, but some basic scrapers don't. If your script doesn't see a JavaScript context, treat that as a high-risk signal.
Inside your script, check that standard APIs exist and behave normally. For example, navigator.userAgent, navigator.webdriver, and properties like window.chrome often reveal automation. A real browser rarely sets webdriver=true. However, this alone is not enough—advanced bots patch it.
The BotRefund Console Debug Evaluator looks for exactly this kind of mismatch: automation tools often patch or hide browser APIs, but those changes break when checked from another angle. So include several API checks and compare them across independent properties.
Step 2: Set Up Event Listeners for Human Interaction
Attach listeners for the events real users generate: mousemove, click, keydown, scroll, touchstart, and touchmove. Bots often send synthetic events without the natural sequence that precedes them.
Use passive listeners for scroll and touch to avoid blocking the main thread. Throttle mousemove to every 50–100 ms so you capture enough data without draining performance.
For each event, record the timestamp, coordinates, target element, and event type. Save these to an array that you can analyze later.
Step 3: Record Timing Patterns
Humans act with natural pauses and variability. Bots act with mechanical precision. Track these timing signals:
- Time between clicks or keypresses.
- Time from page load to first interaction.
- Time spent on the page before scrolling or navigating.
- Input speed—humans take seconds to fill a form, bots can autofill in milliseconds.
BotRefund's Impossible Tab Speed check looks for interactions faster than any human could realistically perform, like sub-millisecond input. Similarly, their session duration signal catches visits that are too short, too long, or too uniform.
Implement a timer that measures the interval between consecutive events. If you see consistent sub-1ms timestamps, flag that session as suspicious.
Step 4: Combine Signals and Build a Scoring System
Do not block on a single anomaly. A privacy browser might disable some APIs, and a corporate proxy can cause unusual timing. Instead, assign weights to each signal and sum them into a risk score.
For example, start with 0 points. Add 20 points if navigator.webdriver is true, 30 points for no mousemove in a 5-second session, 40 points for any input faster than 1ms, and 15 points for a missing API. Set a threshold like 70 to trigger a challenge or block.
BotRefund cross-checks each signal against independent browser, network, device, and behavior data. Their AI model weighs the complete pattern rather than trusting a raw rule. Your scoring system should aim for the same corroboration.
Step 5: Add Honeypot Traps and Hidden Elements
Honeypots are invisible form fields or links that humans never interact with, but bots often fill or click. Place a hidden input in your form with CSS like position:absolute; left:-9999px. If it gets a value, or if you see a click on a hidden element, that's a strong bot signal.
BotRefund's Trap Behavior check watches for bots that respond to hidden or intentionally deceptive page elements. This works because bots often scan the DOM for inputs and fill everything they find.
Also consider a hidden “honeypot link” that real users never see. If it receives a click, flag the session.
Step 6: Handle False Positives and Edge Cases
Privacy tools, travel, corporate networks, and unusual devices can make a real person look like a bot. A user with JavaScript disabled, or a browser extension that spoofs user agent, will trigger your flags.
BotRefund explicitly states: “A single anomaly is not a bot verdict.” They keep each signal as evidence, not a verdict, and cross-check it against independent data. You should do the same—never block based on one check. Instead, if the score is borderline, show a CAPTCHA or a challenge rather than an outright block.
Also consider location and network data. A corporate IP might mask residential proxies, so adjust your thresholds accordingly.
Step 7: Test and Verify Your Script
Run your script in two scenarios:
- Legitimate user: Use a normal browser, move the mouse, click around, scroll, and fill a form. Confirm the score is low.
- Bot: Use a headless browser like Puppeteer or Playwright to automate a session. Confirm the score is high and the block triggers.
Test with incognito mode and with different browsers. Also test with a VPN or proxy to see how network changes affect your signals.
Finally, deploy in a logging-only mode for a few days. Review false positives before you start blocking real traffic.
Key Facts from BotRefund's Detection Approach
| Capability or Claim | Detail |
|---|---|
| Number of checks | 106 independent checks used to build a reliable picture of a visit. |
| Accuracy | Claims 99% accuracy through corroboration and AI prediction. |
| Detection signals | Ghost clicks, honeypot traps, robotic mouse movements, absence of tremor, superhuman input speed, grid-aligned movement, static sessions, unnatural session durations. |
| Ad spend protection | Bot clicks can steal up to 20% of Google and Meta ad budget; BotRefund recovers refunds. |
| Setup time | “Add BotRefund to your website in about one minute.” |
Limitations and When This Approach Doesn't Apply
A self-built script using only browser events and timing will catch simple bots but fail against sophisticated AI-driven botnets. Modern fraud networks use residential proxies and AI to simulate human movement, so your script might not be enough for high-stakes pages.
If you run high-volume paid campaigns, especially on Google or Meta, consider a commercial solution. BotRefund's approach combines behavioral checks with AI and refund recovery, which a basic script cannot match.
Also, server-side factors—IP reputation, device fingerprinting, and network analytics—are often more reliable than client-side JavaScript. A client-only script misses bots that don't execute JavaScript at all.
Terminology to Know
- Headless browser: A browser without a graphical interface, used for automation. Examples: Puppeteer, Selenium, Playwright.
- Honeypot: A hidden element designed to trick bots into interacting with it.
- User agent: A string that identifies the browser and OS. Easily spoofed.
- Residential proxy: An IP address from a real user's device, making bots appear as regular visitors.
- CAPTCHA: A challenge-response test to distinguish human from machine.
Frequently Asked Questions
What is the best bot detection script for a small website?
For a small site, a custom script with event listeners and a simple scoring system is often enough. If you use Google Ads, add BotRefund to recover fraudulent clicks.
How do I know if my script is working?
Test with a headless browser and confirm the score exceeds your threshold. Also monitor your server logs to see if suspicious sessions are being flagged.
Can my bot detection script cause false positives?
Yes. Users with privacy browsers, corporate proxies, or unusual devices may trigger flags. Use a scoring system and require multiple signals before blocking.
How do I handle a bot that passes my script?
No detection method is perfect. If you see suspicious behavior but no flag, adjust weights or add more signals. For advanced bots, consider a commercial service.
Do I need to use a commercial service like BotRefund?
Not always. A self-built script covers basic needs. But if you run paid ads at scale, BotRefund can recover ad spend and provide audit-ready proof.
How long does it take to set up a bot detection script?
Most simple scripts can be set up in an hour. The testing and tuning phase may take a few days, especially if you want to avoid false positives.
Further reading and comparison sources
These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.
Learn more
Visit the website for more information.