Visitor rules
Every request and every pageview is judged by rules: who it is, and what happens to it. Nothing about it is decided by code you cannot see. The rules UsherStats measured on real sites come as a library, already on for you, and every one of them can be read, tuned, switched off or joined by rules of your own.
Who a request is
A rule says something about a visitor when its conditions hold. Together, the rules give every request:
| Actor | person, bot, or unproven: a browser that has not yet shown it is either. |
| Owner | external, or internal: your own team. An internal bot is one of your agents or tools; an internal person is someone of yours reviewing the site by hand. |
| Bot | its name, its type (search engine, AI search, AI assistant, AI training, preview, SEO, monitor, archiver, tool...) and its company. Any of them can be unknown. |
When several rules speak to the same thing, the one with the higher priority wins. The bot's name, type and company come together, from one rule.
A condition tests a signal: something observed, never a judgement. The user agent; whether Cloudflare verified
the crawler; the network (AS number and name); the country; the path; which headers came; the browser's clock and
language; whether the reader scrolled, clicked or typed, and for how long the page was visible; what this visitor did
over the last day; your own marks (a signed tool, a marked browser, a network you named). Text is compared without
regard to case, and a contains list matches if any of its words is part of the value.
Where a rule can act
A rule acts only where everything it tests is known:
- On the server (the Worker SDK and proxy mode), as each request arrives. A browser's clock or whether the reader scrolled is not known yet, so a rule that tests them waits until the page has reported.
- In the analytics, over requests, pageviews and events, when you look at them.
- In A/B readouts, over each session.
The library and the rule editor show where each rule acts. A rule that only tests the browser's own report can still stop a visitor -- from their next request, once the report is in -- but never their first page.
What happens to each visitor
The policy says, for each kind of visitor:
- Where it is counted: as
people, ascrawlers, asinternal-peopleorinternal-agents, orexcludedfrom every view. This decides what the analytics show. It changes nothing that was recorded: change it, and every figure is worked out again from the rows as they were. - Whether it gets in:
allow,challenge(a short check a person passes) orblock. A challenge marked soft is served instead of refused in block mode -- what the Recommended pack does for a browser whose only fault is its network.
A policy names targets, and the most specific one a visitor answers to decides: a bot's name, then its company, then its type, then "a bot with no name", then any bot; a person; an unproven browser; an internal person or agent. Your account's policy sits over the pack's, and a site's own over your account's.
The library and its versions
The library's rules are managed: you switch them on or off, set their parameters (the thresholds and lists are parameters), and choose which version you run -- but you do not edit them. When we publish a better version, you see update available with what changed, and nothing moves until you apply it. Apply updates one at a time or all at once, and go back to an earlier version the same way.
New accounts start with the Recommended pack, everything on. It is what UsherStats did before rules were yours to see: verified crawlers in and counted as crawlers, impersonators out, programs on cloud networks and rented home connections told apart from readers, your own traffic kept apart.
Your own rules
Write a rule of your own the same way: conditions on signals, then what it says about the visitor. A new rule starts in log mode: shown beside your data with what it would have matched, applied to nothing. Switch it on once its matches look right.
Before you save any change, the preview shows what it would do to the last 7 or 30 days: each site's pageviews and requests counted as people, crawlers and internal, now and with the change, and how many readers who scrolled, clicked or typed it would move.
Every save is a new version of your rules, kept with the change in words. Any earlier version can be looked at whole, and restored -- which saves it as the newest version, so nothing is ever lost.
See the API for every route, and Bot protection for modes.