Nudges — messages to a browsing visitor

Everything else in Stitchwork points at your staff. A nudge points at the shopper: a short message across the top of your own site, shown to a visitor whose browsing matched a rule you wrote, while they are still in the session — and measured against a control group that saw nothing, so you can tell whether it did anything.

Nudges are one of the optimisation tools: part of Collection, and an add-on to Independent. On a plan without them your site shows no nudges and the rules you wrote are kept for when they are switched on; tracking carries on either way.

What a nudge is

One line of text, your own words, shown on your own storefront to a visitor who matches a rule. It can ask for an email address, ask for a phone number, point at a page, or just say the thing and get out of the way. It works on visitors who have never told you who they are, which is most of them.

Your tracking tag renders it. There is no second script to paste and nothing to add to your theme — if the tag is installed and consented, nudges work.

What it is not:

• Not live chat. Nobody has to be sitting at a screen. The same rule works on one visitor or ten thousand, at 3am.
• Not an email tool. Nothing is sent. The message exists only in the session it appears in.
• Not a popup builder. One bar, one line, no modal, no overlay across the page, no second banner competing with your consent notice.

Every nudge holds people back

This is the part worth reading before you write one, because it is the part that decides whether the report means anything.

The obvious version of this feature cannot be falsified. Show a banner to interested people, watch some of them buy, credit the banner — when interested people were always the ones most likely to buy. A conversion rate measured on the people who saw it is a measurement of your targeting, and it would look impressive for a nudge that rendered a blank bar.

So a visitor who matches your rule is assigned an arm before anything renders:

Both arms are recorded. Lift is the difference between them — the same people, wanting the same things, split by nothing except whether the bar appeared. That is the only number in this feature that is about the message rather than about who you aimed it at.

The default holdout is 10% — one matching visitor in ten. You can set anything from 0% to 50%. A bigger holdout settles the question faster and costs more showings; 0% turns measurement off entirely, and the report then says so rather than quietly reporting the treated arm's conversion rate as a result.

Writing one

Settings → Nudges. A nudge has five parts:

A nudge is draft, live or paused. Draft is the default — Save as draft writes it without showing it to anybody, and Save & turn on puts it live. You can give one a start date, an end date, or both, which is the difference between a promotion that stops on time and one a customer tells you about a fortnight later.

Write it the way you would say it across a shop floor. A message that reads as "we can see exactly what you have been looking at" lands badly, however true it is. "Still deciding? Our bed specialist can call you back" says the same thing from the customer's side.

Start from your own buyers, not a guess

Writing your first nudge means picking numbers — how many product views counts as interested, how long a pause counts as stalling — with nothing to base them on. A guess produces a rule that fires on everybody or on nobody, and both look like the feature not working.

Seed from my buyers answers it from your own history. It measures what customers who actually bought had done before their first paid order — how many products they had looked at, across how many distinct items, over how many visits — and fills the thresholds in with those numbers. It prints the sentence saying how many customers it learned from.

Below 25 converting customers in the window it returns the shipped defaults and says so. Percentiles over a dozen orders are noise wearing a number's clothes.

What you can ask for

An email or phone CTA should carry a confirmation line — shown once they submit. Without one the bar simply disappears and they type it in again.

Answering twice is one answer. A shopper who submits, reloads and submits again does not open two follow-ups or create two customer records.

Who sees it

A rule is conditions over facts you can count. There is no intent score, no engagement stage and no interest ranking to target on — nothing where the platform decided something on your behalf and you would have to take our word for the result. If a visitor matches what the conditions say, they see the message; if they do not, they do not. The settings form is a builder over this same grammar, and every rule is read back as a plain sentence, so nothing anywhere re-derives what a rule means.

{"all": [
  {"fact": "who.identified",        "op": "is_false"},
  {"fact": "history.product_views", "op": "gte", "value": 6, "within_days": 14},
  {"fact": "history.products",      "op": "gte", "value": 3, "within_days": 14},
  {"fact": "history.orders",        "op": "eq",  "value": 0, "within_days": 365},
  {"fact": "visit.seconds_since_action", "op": "gte", "value": 90}
]}

Read that back and it says what it does: somebody we cannot email, who has looked at six products across three lines in the last fortnight, has never ordered, and has now stopped moving. That last clause is the one worth copying — it stops the bar interrupting somebody who is already busy buying, the single moment a message across the top of the page can cost you a sale.

The facts a rule can name

Each fact has a type, and the type decides its operators. Numbers take eq, ne, gt, gte, lt, lte; text takes eq, ne, in, not_in, starts_with; lists take includes, not_includes; yes/no facts take is_true, is_false. An operator the fact cannot answer is refused when you save it rather than quietly matching nobody for ever. Conditions combine under all or any. GET /api/v1/nudges returns the facts, their types and the operators each one accepts, so a form of your own can build itself from the contract instead of duplicating it.

How often it appears

Three things stop a nudge coming back regardless of frequency:

• They dismissed it. That is an answer.
• They responded to it. Asking again is nagging.
• They are in the holdout. A held-back visitor stays held back — re-evaluating them would leak your control group into the treated arm one page view at a time.

Where several live nudges match the same visitor, the highest priority wins and only one is shown. A visitor never sees two at once.

What it does to your page

Your storefront is not ours to reflow, so the bar overlays rather than pushing the page down. Covering a sticky header for a few seconds is a smaller risk than reflowing a layout we did not write, possibly mid-checkout.

• It lives in a shadow root. Your CSS cannot break it and it cannot break your CSS.
• It is built from text, never from markup. The message is set as text content, so nothing typed into a nudge can execute in a shopper's browser.
• It waits for consent. Exactly the same gate every tracked event waits behind — including your own CMP and Global Privacy Control. Consent withdrawn mid-visit takes the bar down with it.
• It removes itself rather than render broken. If anything fails our end, the shopper sees nothing.
• It never delays your page. The tag asks about a nudge after it has done its own work, on a passive schedule, and stops asking after a few minutes on a page.

A visitor with no __sw_v cookie — no consent, first request, cookies cleared — is a visitor Stitchwork has nothing to target on, and gets no nudge. Nudges are for the second half of a visit, not the first second of it.

Reading the report

Every nudge row has a report behind it. It answers one question — did the message do anything? — and it is written to be capable of answering "we cannot tell yet".

Alongside the verdict:

• Responses — how many were shown it, dismissed it, answered it, how many follow-ups it opened, and how many callbacks are waiting on a name.
• Revenue, per arm and per currency. Read it beside the lift, never instead of it: this is revenue that followed a match, not revenue the nudge caused. As everywhere else in Stitchwork, currencies are never added together — there is no exchange rate in the system, so a combined total would be invented.

The API

The tag calls these for you. They are documented for headless storefronts and native apps, where there is no page for our script to run in.

Rate limited per workspace per minute (2000 by default; ask us if your traffic needs more). Authoring, reporting and seeding are done from Settings → Nudges — those screens authenticate with your signed-in session, so there is no credential to hold and nothing to call them with from outside.

What a nudge can never do

• Reach a visitor who has not consented. Same gate as every event.
• Tell the browser anything but the message. Never the rule that matched, never the profile behind it, never how many other nudges were considered. Your pk_live key ships in your page source, so everything this endpoint returns is readable from any console on your site — and it is written on that assumption.
• Be put in front of a shopper by an AI connection. An MCP agent can propose a nudge — it arrives in your list as a draft, labelled with the agent's name, and a draft cannot render. Turning it on is your act, in Settings → Nudges, audited like every other nudge write; the agent cannot activate, edit, pause or delete anything, its own proposals included. The label survives activation, so a running nudge a machine drafted still says so.
• Be deleted, once it ran. A nudge that ran is evidence about what visitors were shown. Pause it or end it; the record of what it said stays. The one exception is a draft no visitor was ever matched against — a proposal you are rejecting, or a form you abandoned — which can be deleted outright, because a nudge nobody saw is evidence of nothing.

Every write to a nudge is recorded in your audit log with who made it — a note is internal, but a nudge is text shown to a stranger on your storefront, and "who turned this on" is a question that gets asked eventually. A proposal is audited under the agent's own name, and the approval under yours.