Fictura
Paywalls & onboarding

Served designs

A paywall or onboarding flow written in HTML, published from the dashboard, rendered in a hardened webview — the way a brand-new design reaches installed apps.

A served design is raw HTML/CSS/JS stored as the surface's config (template: "webview"). The SDK renders it in react-native-webview and injects a bridge, window.__FICTURA__, before the page's own scripts run. Devices pick a newly published design up on their next config refresh — no release.

A design built in the editor reaches the phone the same way: the server renders it to this HTML. To write one by hand, use ⋯ → Edit HTML on its card. Saving there detaches a design from the editor.

The paywall bridge

packages
array

Live store packages — {id, product_id, price_string, price_micros, currency, period, trial_days…}. Prices are never baked into the HTML, and a config that hardcodes one is rejected; they're injected at runtime from the store adapter.

slots
object

The same packages by slot, so a design never names a product.

trial_eligible
true | false | null

Whether the store will grant the intro trial. null means it has not answered, so gate trial copy on === true.

ineligible_plans · legal · placement · params
values

What to do with a plan this user cannot buy (hide or disable), the app's termsUrl and privacyUrl, the placement, and its params.

device · user · capabilities
values

The values behind {{ device.* }} and {{ user.* }}, read once per showing, and which actions this app can do.

purchase(id)
function

Runs the native store purchase for a package. Buying never happens inside the page.

openWebCheckout(id)
function

Hands off to web checkout when it's available; webCheckoutAvailable says so. Falls back to the store purchase if it can't open.

restore()
function

Restores purchases through the adapter, and shows the result natively.

close()
function

Dismisses the paywall.

track(event, properties)
function

Logs an event, namespaced paywall_web_<event> so a design can't forge funnel metrics. A short list keeps its own name with source: "web": paywall_screen_viewed, paywall_page_viewed, paywall_product_selected, paywall_interacted, exit_offer_shown, exit_offer_accepted, exit_offer_declined. Revenue events are never on it.

openUrl(url, mode) · haptic(kind) · requestReview() · setAttribute(key, value) · presentPlacement(name)
function

What only the app can do. Check capabilities first. See Paywall behaviour.

customAction(name, payload) · requestPermission(name)
Promise

The same, with an answer: a custom action's result from onCustomAction, and whether a permission was granted.

bind()
function

Runs the plan binder again, for plan buttons you added to the page yourself.

Store data can land after the page has loaded. The bridge's values are updated in place, then window.FICTURA_ON_PACKAGES() runs if the page defines it, and a fictura:packages event fires.

Binding plans

The binder ships with the SDK. Tag a button and it buys that plan, with its price filled in:

HTML
<button data-fictura-plan="primary">
  <span data-fictura-price></span> / <span data-fictura-period></span>
</button>

data-fictura-plan resolves as a slot name, then a package id, then a period such as weekly. A button whose plan matches nothing is hidden rather than left dead. data-fictura-trial fills in the trial days.

Changing a design without touching its markup

Edit on a hand-written design opens Fields: its images, colours and words, with the paywall beside them. The values are stored next to the markup and applied at render, so a change can't break the design. HTML beside it opens the markup.

A design can name exactly what is editable with data-fictura-asset, data-fictura-text and --fx-* colours. Without those marks, the fields are read out of the markup.

Saving here over a live paywall asks first — see Saving and publishing.

Hardened by construction

  • A served design cannot navigate to the open web. A tapped http(s) link opens in the system browser and the paywall stays put; images, video and fonts may load over the network.
  • DOM storage and file access are off; new windows are blocked.
  • If react-native-webview isn't installed, or the page can't load, the SDK logs paywall_load_failed and shows "Update the app to see this offer." with a working Close. A paywall a placement presented closes instead.
  • If the page's web process dies, the paywall is brought back, up to twice, and logs paywall_webview_crashed.

Warming and caching

The launch config carries no HTML. The SDK fetches a design by id the first time it's needed, then keeps it for the session and, with AsyncStorage installed, on disk, keyed by version so a new design is never served stale.

To open without a flash, warm it ahead of time. GrowthProvider renders the warm copy off-screen, with an inert bridge, so nothing it does looks like a user.

TypeScript
import { prefetchPlacements } from "@fictura/sdk";

// The first placement is rendered off-screen. The rest get their HTML
// and images cached 5 seconds later (delayMs changes that).
await prefetchPlacements(["default", "credits_exhausted"]);

One design is warm at a time. prefetchServedPaywall(placement, { warm: false }) caches without rendering, and a design can opt out with Prepare in the background in the editor. Growth.preloadPaywalls() fetches campaign paywalls, prioritized first, without rendering them.

Served onboarding

Onboarding has the same mechanism (config template: "webview") with a flow-shaped bridge: window.__FICTURA__.answer(step, value) records an answer, complete(answers) finishes the flow, and track() is namespaced onboarding_web_<event>. Publish from the custom-HTML editor at /dashboard/onboarding. That page opens by direct URL only — it's no longer in the sidebar.

Served designs and native templates share everything else: placements, experiments, automatic funnel events, and the web-checkout-first buy path.

On this page