Preload and sources

Loading fetches a screen without showing it and sends no analytics events. Use it to read what a screen needs before you show it, for example to list its package IDs and fetch prices, or on mobile to warm the cache so present opens at once.

function loadPaywall(source: PaywallSource, init?: RequestInit): Promise<PaywallJson>;

import { configure, loadPaywall, getPackageIds } from '@ui-kit/web';

configure({ apiKey: 'pk_...' });

const paywall = await loadPaywall({ placement: 'upgrade_button' });
const ids = getPackageIds(paywall); // ['monthly', 'annual']
const products = await fetchPricesFor(ids); // your own code

Mobile preload fetches the placements' screens, images and fonts. A placement that cannot be loaded is skipped silently: it never throws. On web there is no separate preload; the SDK keeps its own copy of each answer (below).

SourcesCopy Anchor Link

A JSON object or URL must have the screen format: default_locale, components_config.base and components_localizations. Web unwraps a wrapper object with a paywallData field, and a missing components_localizations becomes {}. Download a screen's JSON with Download JSON on the Screens page. A downloaded file is a copy and does not change when you publish; a placement does.

Caching and the offline copyCopy Anchor Link

For a placement or paywall ID the SDK keeps a copy of the last answer:

1. It sends the last ETag it saw, so an unchanged screen costs a short 304.
2. Web keeps the copy in memory and in localStorage under uikit:v1: plus the request URL, and skips the browser's HTTP cache. Mobile keeps it on disk in the app's cache, with fonts. Icons and catalog fonts a screen uses are named in its delivery, so the phone does not look them up elsewhere. Images are cached for the session (and on disk on iOS).
3. The Miniwall CDN caches an answer for about 30 seconds, so a publish reaches your site or app within about a minute.
4. If the network fails, the request times out or the server answers 5xx, the last copy is used. A published screen keeps working offline.
5. A 4xx answer (wrong key, unknown placement, a website or app that is not allowed) is an error, even if there is a copy.

The timeout is timeoutMs (default 8000 ms; iOS timeout, 8 seconds), set in configure. After it the saved copy is used. With no copy the call fails with UIKit: the paywall took too long to load (web) or Miniwall: the screen took too long to load (mobile).

The delivery responseCopy Anchor Link

For reference, the SDK calls GET {apiUrl}/v1/sdk/placements/KEY?key=pk_...&v=2 (or /v1/sdk/paywalls/ID). Mobile also sends X-Miniwall-SDK (for example ios/0.1.0) and X-Miniwall-App (for example ios:com.acme.app).

Audiences, frequency limit and holdout ship as rules and are decided on the device, so attributes never leave it. See Targeting attributes.

RelatedCopy Anchor Link

• Present a screen
• Purchases and prices (getPackageIds)
• Errors
• Events and privacy