UsherStats Docs Contents usherstats.com Start free

Visitor rules

Visitor rules decide who a request is (a person, a bot, or a browser not yet shown to be either; the site's own or not; which bot, of what type, run by whom) and what happens to it: whether it is let in, and where it is counted. How they work is in Visitor rules. Your account's rules are one versioned whole: reading needs bot:read, changing bot:write with a token that is not limited to some sites. A preview also needs analytics:read.

RouteScope
GET /v1/rulesbot:read
PUT /v1/rulesbot:write
GET /v1/rules/librarybot:read
POST /v1/rules/upgradebot:write
GET /v1/rules/historybot:read
GET /v1/rules/history/{version}bot:read
POST /v1/rules/restorebot:write
POST /v1/rules/previewbot:read
GET /v1/sites/{id}/rulesbot:read

Your rules

A new account runs the Recommended pack: every rule UsherStats has measured on real sites, each one switchable and with its thresholds as parameters you can set.

curl https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN"

The answer is version, state and updates. state holds:

  • refs: the library rules you have, each {id, version, enabled, params}. A library rule is referenced, never copied: it changes only when you apply an update.
  • custom: your own rules, each {id, enabled, mode, sites, rule}. id is own: and letters, digits or -; sites is null for every site or a list; mode is log (watched: shown, not applied) until you set on.
  • policy: analytics (where each kind of visitor is counted: people, crawlers, internal-people, internal-agents or excluded) and access (allow, challenge or block), each by target -- person, unproven, internal-person, internal-agent, bot, unknown-bot, type:<type>, company:<company>, name:<bot>. The most specific target decides.
  • sites: a site's own policy over yours, and the rules it switches off or on for itself.

Changing them

PUT replaces the whole state, made from the version you read as expect. Here a rule of your own -- browsers whose clock is in one time zone -- in log mode, and OpenAI's crawlers left out of the counts:

curl -X PUT https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expect": 1, "state": {"custom": [{"id": "own:fleet", "mode": "log", "rule": {"name": "The Shanghai-clock fleet", "priority": 650, "when": {"all": [{"signal": "tz", "op": "eq", "value": "Asia/Shanghai"}, {"signal": "interacted", "op": "is", "value": false}]}, "then": {"actor": "bot", "type": "proxy-fleet"}}}], "policy": {"analytics": {"company:openai": "excluded"}}}}'

Every save is a new version, kept, with the change in words. A save made from an older version than the one stored is 409: someone saved since, so read them again and make the change on top. A rule a field of which cannot be accepted is 400 with field naming it, and so is a set of rules whose analytics filter would grow past what Analytics Engine takes:

curl -X PUT https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expect": 2, "state": {"custom": [{"id": "own:x", "rule": {"name": "bad", "priority": 1, "when": {"signal": "seconds", "op": "contains", "value": "x"}, "then": {"actor": "bot"}}}]}}'

The library

Every managed rule and every version of it -- what it says, its parameters, where it can act (server, requests, pageviews, events, sessions), its release notes -- the packs, and the signals and operators your own rules can use:

curl https://api.usherstats.com/v1/rules/library \
  -H "Authorization: Bearer $US_TOKEN"

When UsherStats publishes a new version of a rule, GET /v1/rules lists it under updates and nothing changes until you apply it -- all of them, or by id:

curl -X POST https://api.usherstats.com/v1/rules/upgrade \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apply": "all", "expect": 2}'

History

Every version, newest first; one version whole; and going back to one, which saves its rules as a new version:

curl https://api.usherstats.com/v1/rules/history \
  -H "Authorization: Bearer $US_TOKEN"
curl https://api.usherstats.com/v1/rules/history/1 \
  -H "Authorization: Bearer $US_TOKEN"
curl -X POST https://api.usherstats.com/v1/rules/restore \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1, "expect": 3}'

What one site runs

A site's rules in the order they are decided -- from the library, from your account, from the site's own settings -- each with where it can act, the policy the site applies, and the rules only being watched:

curl https://api.usherstats.com/v1/sites \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "hostnames": ["shop.example"]}'
curl https://api.usherstats.com/v1/sites/$SITE_ID/rules \
  -H "Authorization: Bearer $US_TOKEN"

Before you save: a preview

What a state would do to your counts, before it is saved: each site's pageviews and requests in each lane over the last 7 or 30 days, under the rules in force and under these, and the human pageviews where the reader scrolled, clicked or typed -- the people a change would move.

curl -X POST https://api.usherstats.com/v1/rules/preview \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": 7, "state": {"refs": [{"id": "clock-elsewhere", "version": 1, "enabled": false}]}}'

View this page as Markdown