Placements
What a placement is and which of its settings change what the SDK does - display, trigger, audience, frequency, holdout, A/B test and schedule.
A placement is a named slot on your site or in your app, like upgrade_button or pricing. Your code asks the SDK for the placement by its key. Your team decides in the dashboard which screen it shows, how, when and to whom. They can change all of that without a deploy.
UIKit.presentPaywall({ paywall: { placement: 'upgrade_button' }, products, onPurchase });The key
A key uses lowercase letters, numbers, _ and -, up to 64 characters, and is unique in the project. If your code asks for a key that does not exist, or one whose screen is not published, the SDK reports Placement not found or Published paywall not found. See Errors.
Placements can be turned on for Web, iOS and Android separately. A platform that is off gets "not found", as if the key did not exist.
Settings that change SDK behavior
All of these are settings of the placement, not of the screen's JSON. The same screen can be a popup in one place and a banner in another.
| Setting | What it does | Plan | What your code does |
|---|---|---|---|
| Format | Popup, full screen, side drawer, banner, slide-in, toast or launcher, with position and size. Let my code decide is the default. | All | Your mode option wins over the placement's format. See Display modes. |
| Trigger | When to show by itself: page load, after N seconds, at a scroll depth, exit intent (desktop only), app open, app event. Can be limited to page paths and ranked by priority. | All | Call startAutoPlacements() once per page or app. See Auto placements. |
| Audiences | Conditions that choose a screen, or nothing, for matching visitors. First match wins. | Pro | Pass facts with attributes. See Targeting attributes. |
| Frequency limit | At most N views per visit, day, week or in total. | All | Skipped placements resolve with outcome: 'skipped'. |
| Holdout | 5 to 50 percent of visitors see nothing, to measure the placement's effect. | Pro | Call reportPurchase() after every purchase, even from visitors who saw nothing. |
| A/B test | Splits visitors between the placement's screen (A) and a second one (B). Each visitor keeps their side. | Indie | Price every package ID that B uses. |
| Schedule | Another screen between a start and an optional end time. While in force it replaces the screen and pauses the A/B test. Windows on one placement cannot overlap. | Indie | Nothing. |
Audience conditions
An audience has up to 10 conditions, and all must be true. All are checked on the device.
| Condition | Reads |
|---|---|
| Attribute from your site | The attributes you pass (user.NAME). Never sent to Miniwall. |
| Language | The locale option, otherwise the browser language. |
| Device | Phone, tablet or computer, from the user agent (web only). |
| Page path | location.pathname (web only). |
| Times seen | How many times this device was shown the placement. |
| Days since first visit | Whole days since the SDK first evaluated such a condition. |
| App platform, OS version, App version, Country | Set by the native SDKs. False on the web. |
A missing value makes every comparison false except is not and is not set. See Targeting attributes.
Which screen a visitor gets
The delivery response carries the placement's display, trigger, audiences, frequency limit and holdout, and both sides of a running A/B test. The decision runs in the browser or app, in this order:
- A schedule in force replaces the placement's screen and pauses the A/B test.
- Frequency: if the limit is reached, show nothing (
reason: 'frequency_cap'). - Audiences, top to bottom. The first match shows its screen, or nothing (
reason: 'audience'). - If no audience matched, the placement's screen. A running A/B test splits these visitors.
- If the visitor is in the holdout, show nothing (
reason: 'holdout'). - Otherwise the screen opens and a view is counted.
Attributes you pass for audiences are compared in the browser or app. They are never sent to Miniwall. Frequency counters are kept on the device, so a visitor who clears their data starts again. A publish or a placement change reaches your site within about a minute.