# 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`, as `crawlers`, as `internal-people` or `internal-agents`, or `excluded` from
  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) or `block`. 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](api/rules.md) for every route, and [Bot protection](bot-protection.md) for modes.
