Screen and display

Use the Screen & display tab to decide two things about a placement:

1. How the screen appears: as a popup, a full screen, a banner, a slide-in, a toast, a side drawer or a floating launcher button.
2. When it appears: only when your code calls it, or by itself on page load, after a delay, at a scroll depth, or when the visitor is about to leave.

None of this is part of the screen's design. The same screen can be a popup on one placement and a banner on another. The screen's design stays the same.

FormatCopy Anchor Link

The Format section shows cards in two groups, plus a last option for leaving the choice to your code.

Let my code decide is the default for a new placement. It saves nothing about display: your code picks the mode in presentPaywall, and without one the SDK opens a popup. Your code can also override a format you set here. See Display modes in the SDK.

Options for each formatCopy Anchor Link

The form shows the pixel width under the size control, for example 440 px wide, and adds ; a bottom sheet on phones for a slide-in or ; full width on phones for a drawer.

How each format behaves on your siteCopy Anchor Link

The SDK adds no close button of its own: a screen closes with a button in its own design. The templates include one. If you design your own screen, add a button with the action Close the screen (see Actions and links).

Toast. It waits while the visitor points at it, reads it with the keyboard, or has another tab in front, and it never leaves sooner than 2 seconds after they let go. When the time runs out it counts as closed but sends no close event. On phones a toast is as wide as the screen minus 32 px, and Corner becomes bottom center.

Launcher. It is a button, not a screen. It shows once the audience and holdout let the visitor through, and it needs a trigger to appear (choosing Launcher while the trigger is When my code calls it switches the trigger to When the page loads). One launcher button shows per page. When the visitor presses it, the screen opens as a popup or a slide-in and the button hides. When the screen closes the button comes back and takes focus. A slide-in opened from a launcher sits on the same side as the button. The launcher does not use up the page's one screen and does not block other triggers. A frequency limit does not hide the button: it is checked only when the screen would open, and pressing the button on purpose is never held back by it.

Show itCopy Anchor Link

The Show it section chooses the trigger.

For the number options, click into the number box inside the option; that selects the option.

Any option other than When my code calls it makes the placement show by itself. For that your site calls startAutoPlacements() once on every page. The tab reminds you with Your site needs startAutoPlacements() once, on every page. and a Get the code link to Install SDK. See Auto placements.

PagesCopy Anchor Link

This section appears when the trigger shows by itself.

• All pages: the trigger arms on every page.
• Only these pages: type one path pattern per row (placeholder /pricing). Add page adds a row; the suggestion buttons + /pricing and + /blog/* fill a row for you; the remove button at the end of a row deletes it.

Rules for patterns:

• Each starts with / and is at most 200 characters. At most 20 patterns per placement.
• * matches anything, including /. So /blog/* matches /blog/a and /blog/a/b.
• A trailing / does not matter: /pricing/ matches /pricing.
• They are compared with the page's path only (location.pathname), not the query string or the hash.
• If you choose Only these pages and leave every row empty, saving fails with Add a page, or choose All pages.

How oftenCopy Anchor Link

When the placement shows by itself, has no frequency limit yet, is not a launcher, and you are signed in to an account (not the browser-only demo), a How often section offers a checkbox: Limit to once per session, checked by default. It says that each visitor sees the screen once per visit, and that without a limit it shows on every page view and uses your monthly views faster. Saving with it checked also saves a frequency limit of 1 per visit in the Audience tab. Uncheck it to show on every page view.

Saving takes two requests: the display first, then the limit. If the display saves but the limit does not, a toast says Display saved, but the limit wasn't with Retry, and the Audience tab shows Once per session wasn't saved. with Set it now.

PriorityCopy Anchor Link

Priority appears when the trigger shows by itself and at least one other placement in the project shows by itself. It is a whole number from 0 to 100 (default 0). When several placements are due on the same page at the same moment, the higher priority goes first. Equal priorities go to the placement created first. Only one screen shows per page view.

Save, validation and errorsCopy Anchor Link

Errors show under the field when you select Save. See the save bar for what else can fail.

What the SDK does with these settingsCopy Anchor Link

The delivery response for a placement includes its display and trigger. For a call to presentPaywall({ paywall: { placement: 'key' } }):

1. If your code passes mode, that wins and the placement's format, position, size and duration are ignored.
2. Otherwise the placement's format applies.
3. Otherwise the screen opens as a medium popup.

Placements with a trigger are returned by startAutoPlacements(), in priority order. A placement whose screen is not published is left out. An SDK that predates the toast, drawer and launcher formats is sent no display for those three, so it opens a popup. See Versioning.

RelatedCopy Anchor Link

• Display modes in the SDK
• Auto placements
• Audience: frequency limit
• Guide: banner promotion
• Guide: exit-intent offer