How RoutingCat works

RoutingCat shows each visitor one variant of each slot on the pages you choose. It learns from your conversions which variants work, and for whom, and it measures what routing adds. This page explains enough to predict what it does and to read its numbers.

The words

page: a page of your site that RoutingCat can vary.
slot: a place on a page that can change, such as the headline.
variant: one alternative for a slot.
default: the variant your site shows today. Every slot has one.
version: one state of a variant’s content. Each edit makes a new one, and every version is kept.
control: the 10% of visitors who always see the defaults.
visit: a visitor’s 7-day window, below. RoutingCat counts in visits.

From code to visitors

Variants are code: each page has a file in routingcat/ that declares its slots, defaults and variants. Slots vary independently, so every combination of a page’s variants must render.

A production deploy makes changes live within about 2 minutes. npx routingcat plan shows beforehand what will go live.
A preview deploy changes nothing live: its visitors are routed between production’s live variants, and their visits stay out of your results.
In development, RoutingCat serves the defaults and records nothing.
On Hobby, routing starts once a card is on file, with nothing charged, and your sites serve at most 10 live variants together, the defaults not counted: a variant past them is held until there is room. See Plans, billing and emails.

Acts need no deploy. Pausing, resuming, promoting or retiring a variant, reverting a page, or changing a routing setting with the command is live within about 2 minutes.

A production deploy applies only what its code changed since the previous one. So an act holds until a deploy changes the same thing in code, and a pause holds until you resume.

After an act, update the code to match: Change what’s live shows the edit for each act, and npx routingcat status lists where what’s live still differs from your code.

What happens on a visit

RoutingCat picks the visitor’s variants before your page is served, in a root middleware.ts on Vercel, or in RoutingCat’s Worker on Cloudflare. It decides from routing data it refreshes in the background, so no call to RoutingCat waits on the page. On Cloudflare, it adds about 2 to 5 ms of CPU to a routed page (Run it in production).
The visitor keeps the same variants for the whole visit.
A page rendered at each request renders what was picked. A prerendered page, or one Vercel keeps for every visitor, carries every variant, the same for everyone, and <RoutingCat /> shows the visitor’s own before the page paints. The browser then reports what each page showed.
Your server reports conversions, and links visitors to their accounts: see Track conversions.
A conversion is credited through the visitor or their account, so it counts even on another device.

RoutingCat also notes where each visit came from, on every page it runs on, routed or not, which is how sources shows where conversions come from.

Visits and windows

A visit starts the first time a visitor reaches a routed page, and lasts 7 days by default.

A conversion counts for a page when it happens within the objective’s window after the visitor first saw that page, 24 hours by default. It counts at most once per visit.

Maturity. Once the window has closed, the visit’s outcome is known, and the visit has matured.

Figures over matured visits are settled.
Figures over all visits so far are marked incomplete, and read low, since recent visits can still convert.

See Conversions and visits.

How routing learns

Routing learns to get more of each page’s objective: the main conversion you declare, such as signup. Other outcomes you track, such as purchase, are reported beside it but never steer routing.

Routing is a contextual bandit:

A Bayesian model of each page estimates how likely each variant is to convert, and for whom.
Thompson sampling gives each variant traffic in line with the probability that it is the best.

In practice:

It learns once a day on Hobby, and on Pro as conversions mature, at most hourly, from visits whose outcome is known. With the default window, a visit starts to shape routing a day or two later on Hobby, about a day later on Pro.
It favors what is likely best, and keeps exploring. An uncertain variant keeps being shown until the evidence settles, and a small random slice of visits is always split evenly.
It learns for whom, not only what. When some visitors respond differently from others, routing can learn to show them different variants. Each such difference must earn its place with evidence; until then, everyone is routed alike.
New variants start cautiously, from what the page’s other variants taught it, with a limited share of traffic until evidence builds.
An edit is not a new idea. An edit under the same key builds on what the variant already showed. A new idea goes under a new key and is compared with the default at the same time.

Two settings change this per slot:

A fixed share splits traffic evenly and keeps each visitor on the same variant across visits. At 1, it is a classic A/B test, the right choice for prices, since routing toward conversions would favor the cheaper price.
Personalization off routes every visitor the same way.

See How routing learns and Routing settings.

The control and the measured gain

The control is 10% of visitors, chosen at random, who always see the defaults, on every page and every visit. Because the choice is random, comparing routed visits with the control measures what routing changed, without relying on the model.

A page’s measured gain is the extra conversions its routed visits produced, compared with showing everyone the defaults, with a 95% range.

A range that spans zero means the direction isn’t known yet. “+23 sign-ups, between −95 and +141” is too early to call.
A promote keeps it. A promoted variant becomes the default, which the control sees too, and measurement continues against the new defaults.
Each page’s gain stands alone. Visitors see several pages, so gains don’t add up to a site total.
The range is not a stopping rule. Checking daily and acting on the first good day overstates gains.

Three kinds of number

Kind	Examples	Read it as
Counted	Visits, conversions, rates, revenue, the share each variant was shown	What happened. Exact, but routing shows variants to different visitors, so raw rates aren’t a fair comparison.
Predicted	A variant’s predicted rate, its difference from the default, signal, labels	The model’s current belief, with a 95% range. It moves as evidence arrives, and holds only as far as the model fits your visitors.
Measured	The measured gain, and a fixed share’s comparison of its variants	From a comparison set up by chance, without the model. The measured gain is the only figure that counts as a gain.

Signal says how much evidence backs a variant’s predicted rate, from 0 to 100: New, Early, Building, Strong. It is not a probability of winning.

Labels say what routing does now:

favored: the variant it intends to show most;
learning or prior: whether the estimate comes from your own results yet.

None is a verdict: what to keep is a judgment on the evidence, yours or your agent’s. See What the numbers mean.

What updates when

What	When
A deploy or an act reaching visitors	Within about 2 minutes
Live activity	Within a minute
Counts, and most warnings	Every hour; every 15 minutes on Pro
Learning	Once a day; on Pro, as conversions mature, at most hourly
The measured gain	Once a day
Predictions	After each fit of the model, and soon after each deploy or act

When something fails

Visitors always get a page:

If RoutingCat is unreachable, routing continues with what it last knew, or the page shows its defaults.
A build that can’t reach RoutingCat ships as usual, with the defaults.
A browser too old to show a selection, Safari before 16.4, Chrome before 105 or Firefox before 121, gets the defaults, whether the page is prerendered or rendered at each request.