Seatext library / BotRefund evidence
Bot Detection Script Compatibility with CMS: How Client-Side Detection Works Across Platforms
BotRefund's detection script is a lightweight JavaScript snippet that runs in the visitor's browser, not on your server. Because it operates client-side, it works with any CMS — WordPress, Shopify, Webflow, Squarespace, Wix, or...
✓ Built for advertisers who need clear, refund-ready traffic evidence.
Why CMS compatibility is rarely the blocker
Most modern bot detection services, including BotRefund, deliver a single JavaScript file that loads asynchronously in the browser. The script observes mouse movement, click timing, scroll behavior, and network signals — all of which happen after the page reaches the visitor. Your CMS only needs to output the snippet on every page you want protected. If you can edit the global header, footer, or use Google Tag Manager, you can install it.
How the script fits into common CMS architectures
WordPress
Paste the snippet into your theme's header.php before the closing </head> tag, or use a header/footer plugin such as "Insert Headers and Footers." If you use a caching plugin, clear the cache after saving so the script appears on cached pages.
Shopify
Go to Online Store > Themes > Edit code > theme.liquid and paste the snippet above </head>. Shopify Plus merchants can also add it via the Scripts section in Settings > Checkout for post-purchase pages.
Webflow
Open Project Settings > Custom Code > Head Code and paste the snippet. Publish the site. The script loads on every page, including CMS Collection pages and Ecommerce templates.
Squarespace
Navigate to Settings > Advanced > Code Injection > Header and paste the snippet. Save and refresh. Squarespace loads the code on all standard pages and blog posts.
Wix
Use Settings > Custom Code > Add Custom Code > Head. Paste the snippet and apply to all pages. Wix's Velo environment also lets you load the script conditionally if needed.
Custom or headless builds
Include the script tag in your base layout or template so it renders on every route. For single-page applications, ensure the script initializes after each route change — most detection scripts expose a re-init function for this purpose.
Integration methods compared
| Method | Setup effort | Coverage | Best for |
|---|---|---|---|
| Direct header paste | Low — one paste per site | All pages using that template | Small sites, quick tests |
| Google Tag Manager | Low — one container publish | All pages with GTM container | Teams managing multiple tags |
| CMS plugin or app | Medium — install and configure | All pages, often with admin UI | Non-technical editors |
| Server-side include | Medium — edit layout files | All rendered pages | Static site generators |
BotRefund's own guidance emphasizes a one-minute install with no credit card, which aligns with the direct header or GTM approach. The source pack notes "Add BotRefund to your website in about one minute" and "Fast Setup z8y Typical time to add BotRefund to your website and start your free bot audit."
What the script actually does on the page
Once loaded, the script runs 106 independent checks across browser, network, device, and behavior layers. These include:
- Click behavior: Ghost click detection catches clicks without human intent sequence.
- Trap behavior: Honeypot interactions reveal bots responding to hidden elements.
- Pointer behavior: Robotic linear mouse movements flag unnaturally straight paths.
- Motion behavior: Absence of humanlike mouse tremor looks for missing micro-jitter.
- Speed behavior: Superhuman input speed (<1ms) identifies impossible reaction times.
- Path behavior: Grid-aligned movement detects snapping to precise lines.
- Engagement behavior: Absence of clicks or scrolling highlights static sessions.
- Session behavior: Unnatural durations catch visits too short, long, or uniform.
- Network signals: Suspicious Ports check finds proxy rotation or location masking mismatches.
- Biometric signals: Monitor Sync Anomaly detects timing and hesitation patterns scripts struggle to replicate.
Each signal feeds an AI model that weighs the complete pattern. The source pack states: "BotRefund sends this signal into our prediction AI, which evaluates the complete picture across browser, network, device, and behavior evidence. By seeing how all signals fit together, it identifies a visit as bot or human with z8y 99% accuracy."
Common compatibility questions
Does the script conflict with other JavaScript?
It loads asynchronously and namespaces its functions, so conflicts are rare. If you run multiple analytics or chat widgets, load the detection script first so it captures the earliest interactions.
Will it slow down my pages?
The script is designed to be lightweight and non-blocking. It defers heavy computation until after the page is interactive. Most sites see no measurable impact on Core Web Vitals.
What about Content Security Policy (CSP)?
If your CSP restricts external scripts, add the script's domain to your script-src directive. The vendor can provide the exact domain and hash for strict policies.
Does it work on AMP pages?
AMP restricts custom JavaScript. You would need the vendor's AMP-compatible endpoint or a server-side alternative. Check with the vendor for current AMP support.
Can I exclude admin or preview URLs?
Yes. Most CMSs let you conditionally output the snippet — for example, only when !is_user_logged_in() in WordPress or via GTM triggers that fire on specific page paths.
Key facts
| Fact | Detail |
|---|---|
| Installation time | About one minute to add to website |
| Detection checks | 106 independent signals across browser, network, device, behavior |
| Accuracy claim | 99% via AI model weighing complete pattern |
| Refund coverage | Google Ads and Meta ad spend dating back to 2017 |
| Customer refund success | 83% of customers successfully get a refund |
| Setup requirement | No credit card required for free bot audit |
| Signal philosophy | Each anomaly is evidence, not a verdict; cross-checked across layers |
Limitations and when this advice does not apply
- Server-side bot filtering: This article covers client-side JavaScript detection. If you need to block bots before they hit your application (e.g., at the CDN or WAF layer), you need a different solution.
- AMP and locked-down environments: Platforms that forbid custom JavaScript (AMP, some enterprise portals with strict CSP) cannot run the standard snippet.
- Native mobile apps: The script runs in web views only. In-app traffic requires an SDK.
- Privacy regulations: The script collects behavioral biometrics. Ensure your privacy policy discloses this and you have a lawful basis under GDPR, CCPA, or other applicable laws.
- Single-page app routing: You must re-initialize the detector on route changes; otherwise, subsequent virtual pages go unmonitored.
Terminology
- Client-side detection: Code that runs in the visitor's browser to observe behavior.
- Honeypot: A hidden page element (link, field) that humans ignore but bots interact with.
- Mouse tremor: The microscopic, involuntary jitter in human cursor movement.
- Superhuman input speed: Interactions faster than ~1 millisecond, beyond human neuromuscular limits.
- Grid-aligned movement: Cursor paths that snap to exact pixel coordinates, typical of scripted automation.
- Suspicious Ports: Network ports commonly used by proxy rotation services or data-center exit nodes.
- Monitor Sync Anomaly: Mismatch between reported screen refresh timing and actual event timestamps.
FAQ
Do I need a different snippet for each CMS?
No. The same JavaScript snippet works everywhere. You only change how you inject it — theme file, plugin, GTM, or code injection setting.
Can I test the script before going live?
Yes. Add it to a staging or preview environment first. BotRefund offers a free bot audit that starts as soon as the script loads, so you can verify detection on test traffic.
What if my CMS minifies or concatenates scripts?
Exclude the detection script from minification or concatenation. Load it directly via a separate <script src="..." async></script> tag to avoid syntax errors or delayed execution.
Does the script set cookies or use localStorage?
It may set a first-party identifier to stitch sessions. Treat this as personal data under privacy laws and disclose it in your cookie notice.
How do I know it's working?
Open the browser dev tools console after page load. The script typically logs an initialization message. In BotRefund's dashboard, you'll see live session data within minutes of the first visit.
Can I run it alongside Cloudflare Bot Fight Mode or similar?
Yes. Cloudflare operates at the edge; this script operates in the browser. They complement each other — edge filtering catches known bad actors, client-side detection catches sophisticated bots that bypass edge rules.
What happens if a visitor blocks JavaScript?
The script cannot run, so that session goes undetected by this layer. Pair with server-side log analysis for complete coverage.
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.