Fictura
Paywalls & onboarding

Placements and campaigns

Name a moment in your app once. The dashboard decides who sees which paywall there, how often, and who is held out — decided on the device, with no release.

A placement is a named moment in your app, like credits_exhausted. A campaign holds placements and an ordered list of audiences, and each audience splits people between paywalls. The decision runs on the device, so it is instant and works offline from the cached config.

In your app

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

await Growth.register({
  placement: "credits_exhausted",
  params: { tool: "redesign", credits_left: 0 },
  feature: () => startRedesign(),   // runs when the user should get it
  handler: {
    onPresent: (info) => {},
    onDismiss: (info, result) => {}, // purchased | restored | declined
    onSkip: (reason) => {},          // holdout | no_audience_match | placement_not_found | placement_paused | user_is_subscribed
    onError: (error) => {},          // presentation error: your fallback
  },
});

register resolves once the placement has finished and never rejects. GrowthProvider presents the paywall, so there is nothing else to mount. One shows at a time: registering while one is up gives onError. Names match ^[a-z0-9_]{1,64}$, and new ones appear on the dashboard by themselves.

<GrowthPaywall placement> runs the same pipeline in place, and renders your fallback for a holdout or a skip. For the other ways in — usePlacement, getPresentationResult, presentIfNeeded, getPaywallForPlacement, preloadPaywalls — see the SDK reference.

Params become params.* in audience rules and {{params.key}} text in a served design. Strings up to 200 characters, numbers, booleans and dates are kept, up to 50 keys. $-prefixed keys, arrays, objects and nulls are dropped.

On the dashboard

Monetize → Placements lists every placement with its campaign. Ones the app has reported but no campaign holds are flagged under Seen in app, not in a campaign.

The Campaigns tab on that page lists campaigns. When no audience matches picks a default campaign that catches everyone a placement's own campaign does not; without one, they see no paywall.

A campaign has three tabs: Placements, Audiences and Results, plus an Active switch and a Prioritize switch, whose paywalls preload first. One campaign per app can be prioritized.

Audiences

Checked top to bottom, and the first one a user matches decides. Each has:

SectionWhat it sets
WhoA rule. Empty matches everyone who reaches the placement
SubscriptionNot subscribed, Everyone or Subscribers only
How oftenA frequency limit, counted per device each time a paywall from this audience shows
WhenLive, Scheduled with a start and optional end, or Inactive, which falls through to the next audience
PaywallsVariants and their shares. Whatever the shares leave is the holdout, who see nothing, so you can measure what the paywall adds

A rule goes up to 3 levels deep and 25 conditions. A field the device does not have makes its condition false. It can test:

  • user.<attribute>, from setAttributes, plus user.seed (0–99) and user.is_logged_in
  • params.<key> and event_name
  • device.platform, app_version, app_build, os_version, device_model, locale, language, region, currency, timezone_offset, interface_style, is_low_power, days_since_install, minutes_since_install, days_since_last_paywall_view, total_paywall_views, is_sandbox, is_first_app_open, sdk_version
  • server.country, server.billing_state, server.attribution.media_source, .campaign, .ad_set, .ad, .link_slug
  • computed.minutes_since, hours_since, days_since, placements_in_hour, placements_in_day, placements_in_week, placements_in_month or placements_since_install, followed by a placement name

Hour, weekday and screen size are for designs

SDK 0.23 also reports device.local_hour, local_weekday, uses_24h_clock, screen_width, screen_height, is_tablet and font_scale. A paywall's own conditions can read them — see Paywall behaviour. Audience rules cannot use them yet.

Results

Per variant in an audience, over 7, 14, 30 or 90 days: users, views, conversions, trials, proceeds, proceeds per user and the chance it is the best, against the holdout when there is one.

Feature gating

Set per paywall, from ⋯ → Presentation on its card or On the phone in the editor. It decides when feature runs:

OutcomeNot gatedGated
Any skip (holdout, no match…)RunsRuns
Purchased or restoredRunsRuns
DeclinedRuns—
Closed to open the next paywall——
Presentation error— (onError)— (onError)

The same dialog sets the style — Fullscreen, Modal, Drawer or No animation — and a delay before it shows, up to 10 seconds.

Implicit placements

Add a placement with one of these names to a campaign and the SDK triggers it itself. Unconfigured names cost nothing.

PlacementWhen
app_installFirst launch
app_launchEvery cold start
session_startLaunch, or a return after over an hour away
deep_link_openAny deep link
paywall_declineA paywall was closed
transaction_abandonThe store sheet was cancelled
transaction_failThe purchase failed
survey_responseThe cancel survey was answered
touches_beganThe first touch, once

The three after a paywall replace the current one and never chain another.

Events

placement_triggered carries result: paywall, holdout, no_audience_match, placement_not_found, placement_paused or paywall_not_available. paywall_presentation_request says whether it presented. Every paywall event carries campaign_id, audience_id and presented_by.

On this page