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.
| Route | Scope |
|---|---|
GET /v1/rules | bot:read |
PUT /v1/rules | bot:write |
GET /v1/rules/library | bot:read |
POST /v1/rules/upgrade | bot:write |
GET /v1/rules/history | bot:read |
GET /v1/rules/history/{version} | bot:read |
POST /v1/rules/restore | bot:write |
POST /v1/rules/preview | bot:read |
GET /v1/sites/{id}/rules | bot: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}.idisown:and letters, digits or-;sitesisnullfor every site or a list;modeislog(watched: shown, not applied) until you seton.policy:analytics(where each kind of visitor is counted:people,crawlers,internal-people,internal-agentsorexcluded) andaccess(allow,challengeorblock), 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 ownpolicyover yours, and the rules it switchesofforonfor 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}]}}'