Auto placements
Let placements show themselves on page load, after a delay, at a scroll depth or on exit intent, with one call.
Placements that have a trigger in the dashboard (see Screen and display) show themselves. Your site needs one call, once per page:
function startAutoPlacements(options?: AutoPlacementsOptions): AutoPlacementsHandle;UIKit.configure({ apiKey: 'pk_...' });
const auto = UIKit.startAutoPlacements({
products: { monthly: { price: 9.99, currency: 'USD', period: 'month' } },
onPurchase: async ({ packageId }) => startCheckout(packageId),
onAction: ({ actionId }) => handleAction(actionId),
onResult: ({ placement, result }) => console.log(placement, result),
});Options
AutoPlacementsOptions takes every presentPaywall option except paywall, mode, position, size, duration and closeOnBackdrop (the placement sets the format). Options are read when a screen opens, so prices you load later are used.
One extra option:
| Option | Type | What it does |
|---|---|---|
onResult | ({ placement, result }) => void | Called when a screen shown by a trigger finishes, or targeting chose to show nothing. result is a PurchaseResult. |
Load failures go to onError. They are never thrown.
The handle
| Member | What it does |
|---|---|
refresh() | Re-arms the triggers for the current page now, for example after a route change the SDK did not notice. |
stop() | Removes every trigger and the launcher button. A screen that is already open stays open. |
Calling startAutoPlacements again while one is active returns the same handle. Without a window (server rendering) it returns a handle that does nothing.
Triggers
| Trigger | Fires |
|---|---|
page_load | When the page has loaded (immediately if it already has). |
delay | After seconds seconds. |
scroll | When percent percent of the page has been scrolled. A page that cannot scroll counts as 100%. |
exit_intent | When the pointer leaves through the top of the window. Never on touch-only devices (hover: none). |
manual | Never by itself. |
A trigger may list pages. They are matched against the page's path: * matches anything, a trailing / is ignored, and no patterns means every page.
The queue
- One screen per page view. Once an automatic screen has opened, the other triggers of that page view are dropped.
- Never over another screen. If any screen is open (automatic or yours), a trigger that fires is dropped.
- By priority. If several fire at once, the highest
prioritygoes first, then the placement created first. A placement that targeting skips (frequency, audience, holdout) lets the next one try. - Route changes. The SDK watches
location.pathname(thepopstateevent and a check every second). A new path is a new page view: old triggers are removed and new ones armed. - Your own call. If you call
presentPaywallwhile an automatic screen is open, the automatic one closes withclosed.
The list comes from GET /v1/sdk/auto. It leaves out placements with a manual trigger and placements with no published screen to show.
Launcher
A placement whose format is Launcher shows a floating button instead of a screen. The button needs its label, appears when the audience and holdout allow, and is one per page. It does not use the page's one screen. Pressing it opens the screen as a popup or a slide-in, hides the button, and brings it back with focus when the screen closes. The frequency limit is not applied to the button and pressing it is never held back by it.
React
Use useAutoPlacements(options) once, in your root layout. See React.