Seatext library / BotRefund evidence
Detect Headless Browser Automation with BotRefund: Step‑by‑Step Guide
BotRefund flags headless automation by analyzing browser fingerprints, JavaScript execution quirks, and network signals. Follow these steps to enable the checks, interpret the signals, and verify that headless traffic is being caught.
✓ Built for advertisers who need clear, refund-ready traffic evidence.
BotRefund can spot headless browsers by looking for mismatches in low‑level browser APIs that real users never produce. Enable the built‑in checks, review the signals, and set up alerts to catch automated traffic.
Prerequisites
- Access to your website’s code to add the BotRefund client script.
- A BotRefund account with the dashboard view.
- Basic knowledge of JavaScript deployment (e.g., via tag manager).
- Familiarity with your ad platforms (Google Ads, Meta Ads) to map click IDs later.
How BotRefund Detects Headless Browsers
BotRefund runs over 100 independent checks on every visit. Each check produces a signal — an objective fact about the browser environment. No single signal equals a bot verdict. The system cross‑checks signals across browser, network, device, and behavior layers, then feeds the full pattern into an AI model that assigns a confidence score. This corroboration approach is why BotRefund reaches 99% accuracy in flagging automated traffic.
Headless browsers such as Playwright, Puppeteer, and Selenium often patch or hide native APIs to avoid detection. Those patches create subtle inconsistencies: mismatched property values, impossible rendering metrics, or altered iframe contexts. BotRefund’s signals target those inconsistencies.
Key Signals for Headless Detection
| Signal | What It Checks | Why It Indicates Automation |
|---|---|---|
| Playwright Init Scripts | Mismatch in Playwright‑specific API values | Automation tools patch these APIs; real browsers never show the mismatch |
| Clean Context Iframe | Inconsistent iframe context properties | Headless tools often hide or alter iframe behavior |
| Scrollbar Width Leak | Impossible scrollbar width values | Scripts cannot reliably reproduce native scrollbar dimensions |
Each signal is independent evidence. BotRefund does not treat any one as conclusive. Privacy tools, corporate VPNs, or unusual devices can produce anomalies for genuine visitors. The AI model weighs the complete pattern before assigning a high‑confidence verdict.
Step‑by‑Step Implementation
- Activate BotRefund on your site. Insert the provided script tag before the closing
<body>tag or through your tag manager. The script loads asynchronously and begins collecting signals immediately. - Enable headless‑specific checks. In the dashboard, navigate to the detection settings and turn on the following signals:
- Playwright Init Scripts – detects patched or hidden Playwright APIs.
- Clean Context Iframe – catches mismatched iframe contexts used by automation.
- Scrollbar Width Leak – looks for impossible scrollbar dimensions.
- Configure alert thresholds. Set the confidence level (e.g., 90%+) at which a session is flagged as automated. Higher thresholds reduce false positives; lower thresholds catch more sophisticated bots. Start at 90% and adjust after reviewing flagged sessions for a week.
- Map click IDs to sessions. Ensure your landing pages capture Google Click IDs (GCLID) and Meta Click IDs (fbclid) in the URL. BotRefund attaches these IDs to flagged sessions so refund reports reference the exact paid clicks.
- Monitor the BotRefund dashboard. Review flagged sessions daily. Each entry shows the specific signals that triggered the alert, a session replay, and the confidence score.
- Export evidence for refunds. Use the built‑in report generator to create platform‑ready documentation (Google, Meta, etc.). Reports include click IDs, timestamps, signal explanations, and session recordings formatted for ad‑platform reviewers.
Verify Detection Works
Run a simple headless script (e.g., Playwright or Puppeteer) against a test page that has BotRefund enabled. After the visit, check the dashboard for a flagged session and confirm that one of the enabled signals appears. Repeat with different headless configurations (headless: true, headless: false, stealth plugins) to see how coverage varies.
Interpreting Flagged Sessions
When a session is flagged, open the session detail view. You will see a list of triggered signals, each with a plain‑language explanation. Look for clusters: multiple headless signals plus behavioral anomalies (superhuman click speed, linear mouse paths, no scroll tremor) increase confidence. A single signal in isolation may stem from a privacy extension or unusual device — treat it as a lead, not a verdict.
Common Mistakes to Avoid
- Relying on a single signal as proof of a bot. BotRefund treats each signal as evidence and cross‑checks it with dozens of other behavioral cues before assigning a high‑confidence verdict.
- Setting the confidence threshold too low initially. This floods the dashboard with borderline sessions and makes review inefficient. Start high, then lower gradually.
- Not capturing click IDs. Without GCLID or fbclid, you cannot tie flagged sessions to specific paid clicks, which blocks refund claims.
- Ignoring false‑positive patterns. If a specific corporate VPN or privacy tool consistently triggers one signal, add a suppression rule for that signal in that context rather than disabling the signal globally.
Practical Scenarios
- E‑commerce site seeing high cart‑abandonment from paid traffic. Enable headless checks, filter flagged sessions by campaign, and submit refund claims for the associated click IDs.
- Lead‑gen form receiving spam submissions. Correlate flagged headless sessions with form‑submit events. Use the session replay to confirm automated form filling, then block the source IPs at the CDN layer.
- Agency managing multiple client accounts. Deploy BotRefund via a shared tag‑manager container. Use the dashboard’s multi‑account view to compare bot rates across clients and prioritize refund efforts.
Limitations
BotRefund does not rely on a single check; a lone anomaly is not a verdict. Privacy tools, corporate VPNs, or unusual devices can produce false positives, so each flagged session is reviewed against the full signal set. The system works client‑side only; it cannot see server‑side logs unless you integrate them separately. Sophisticated adversaries who perfectly replicate browser fingerprints may evade detection, though this is rare and requires constant maintenance on their part.
Terminology
- Signal: An independent piece of evidence (e.g., Playwright Init Scripts) that contributes to the overall bot confidence score.
- Confidence Score: The AI‑driven probability that a session is automated, expressed as a percentage.
- Refund‑Ready Report: A formatted document that includes click IDs, timestamps, and signal explanations for ad platform reviewers.
- Click ID (GCLID / fbclid): Unique identifiers appended to landing‑page URLs by Google Ads and Meta Ads, used to tie a session to a specific paid click.
- Session Replay: A visual reconstruction of the visitor’s mouse movements, scrolls, clicks, and typing, captured by the BotRefund script.
FAQ
- What if I get false positives? Review the full session replay; BotRefund flags only when multiple signals align. If a specific tool (e.g., a password manager) triggers a signal, add a suppression rule for that signal in the dashboard.
- Can I detect custom headless tools? Yes – any tool that alters browser APIs will likely trigger at least one of the built‑in checks. BotRefund’s signal library is updated regularly to cover new automation frameworks.
- Do I need server‑side logs? Not for detection. BotRefund works entirely client‑side, though server logs can complement the analysis and help correlate IP‑level patterns.
- How fast are alerts? Signals are processed in real time; flagged sessions appear in the dashboard within seconds of the visit.
- Is there an extra cost for headless detection? No – the checks are part of the standard BotRefund package.
- Can I export raw signal data for my own analysis? Yes. The dashboard provides CSV and JSON exports with every signal, timestamp, and confidence score per session.
- What happens if a visitor uses a privacy‑focused browser like Brave or Tor? Those browsers may trigger some signals (e.g., fingerprinting resistance). BotRefund’s cross‑check logic accounts for known privacy‑browser patterns, so they rarely reach high confidence on their own.
- How do I submit a refund claim to Google or Meta? Generate a refund‑ready report in the dashboard, download it, and attach it to the platform’s invalid‑traffic claim form. BotRefund’s reports are structured to match the evidence format each platform expects.
Further reading and comparison sources
These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.
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.