Placements

A placement is the named spot your app asks for a flow by — your app names the spot, and the placement decides which flow comes back.

What it is

Your app calls present("paywall"). The placement keyed paywall decides what comes back. Your app never names a flow, which is what lets you change what people see without shipping a build.

A placement holds a name, a key, what it is for, and an ordered list of lanes. You make one here, on its own — creating a flow never makes one, and does not require one either. The place first, then who it is for, then what they get.

Keys are lowercase words separated by single hyphens, and unique within a project. What it is for is a closed list: Onboarding, Paywall, Offboarding, Survey, Announcement, Promotion, Something else.

Lanes

A lane is one row of that list: an Audience and the Flow it gets. Lanes are ordered and the first row that matches wins. The last lane has no audience — it reads Everyone else, catches everyone the others missed, and cannot be removed or moved. A placement holds at most 8 lanes — up to seven audiences plus the one that catches everyone else; past that the groups are too small to tell you anything.

A lane can serve nothing on purpose. Set Flow to Nothing — the app shows its own screen and those installs get whatever your app shows when a flow is unavailable. That is how you roll something out against nothing: the control is the absence of a flow, the candidate is the treatment, and the share going to the candidate ramps up.

Every lane sets its own Held back share — the part of that audience kept out of every test there, so a group always sees the original to compare against. Whole percent, 5 to 50, and 10 on a new lane. Two lanes serving the same flow must hold back the same amount, because the tests on that flow are measured against one reserve.

One flow is served through one placement. If you want the same screens at two addresses, copy the flow. And once a placement has more than one lane, apps on an older SDK are given the flow for everyone else and are left out of tests here.

What the badge says

Live — answering on at least one channel right now.
Not published — it has lanes, and no release is answering yet.
Not configured — no lanes. It exists and its key is taken; it serves nothing.
Archived — filed away, off the index until you show archived placements.

The verbs

Publish rebuilds the release from the current lanes. It mints no flow version and points no lane anywhere new — every lane keeps serving the version it was already serving. It goes to production unless you pick staging. A placement whose lanes serve nothing has no flow to publish through, so this is the only way to start it.

Take offline stops the placement answering on one channel — every lane at once, which is what a release is. Installs already running a flow from here lose it. Publishing again puts it back.

Archive takes it off the index and keeps everything it handed out. It is refused while the placement still routes anything and while it is still answering on a channel; take it offline first, and empty it by deleting the flows its lanes serve — the lanes go with them. This is the one case where deleting a flow is the ordinary move rather than the exception, because archiving a flow leaves its lane behind. The key stays taken either way, because fielded apps still ask for it. Restore brings it back.

Delete is the undo for a placement created by mistake, and only that: no lanes, no live release on any channel, no history, and no test that ever ran. Anything that has served installs is archived instead, because what it handed out is the only record of what those people saw. The console offers whichever of the two is legal.

Tests and limits

A placement runs flow tests — arms that are whole flows, listed under the audience they draw from, because a lane is the population a test measures. These are the tests that earn a flow the In a test badge, and they are separate from the screen-level tests configured inside a flow. A test measures a published plan, so starting one is refused until the live production release carries it — publish first. Concluding a test promotes the winner by repointing the lane, and the reason is written into the history.

Limits — in the kebab menu on the placement — sets how much worse a version may be than the original before it can no longer be promoted. Three guardrails ship with every placement: how many people give up on the flow (default 2pp), how many start it again (2pp), and how long it takes to finish (10 seconds).

The two rate limits are in percentage points, not percent: a 2pp limit means two more people in every hundred than the original, whether the original loses 5% or 40%. The console words it that way and offers 1pp, 2pp and 5pp as one click, so the distinction never rests on reading a suffix. Seconds get no suggested values, because the right number depends on the flow — a deliberately longer, better-qualified onboarding should not be judged against the same limit as a two-screen one.

You can change a threshold, and nothing else: a guardrail cannot be removed, its direction cannot be flipped, and it cannot be set to no limit — a check that can never fire reads on the results panel as a test that passed. The limits belong to the placement, so they apply to every test on it. Changing one re-judges results already collected, including on a test currently running, so set the floors before you launch; moving one mid-test changes the verdict on data you have already seen.

A crossed limit takes the Promote button away — it does not stop the test. The results panel names what got worse and by how much, and the losing version keeps being served to its share of people until you act. Stopping is Pause on the test itself, which puts everybody back on the flow the lane already served within seconds and needs no publish.

Two things follow from that, and they are worth knowing before you rely on a limit. It is a check on your decision, not a circuit breaker: nothing is withdrawn from anybody automatically. And a limit only fires once there is enough evidence — it compares the cautious end of the measurement, not the raw difference, so a small test can show a bad result without crossing anything. On low traffic that is most of them.

Flows are what a lane serves. Audiences are the rules a lane routes by, and they belong to the project — any placement can use one. The SDK page covers the present() call itself, and Health is where delivery failures land.