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
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:
| Section | What it sets |
|---|---|
| Who | A rule. Empty matches everyone who reaches the placement |
| Subscription | Not subscribed, Everyone or Subscribers only |
| How often | A frequency limit, counted per device each time a paywall from this audience shows |
| When | Live, Scheduled with a start and optional end, or Inactive, which falls through to the next audience |
| Paywalls | Variants 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>, fromsetAttributes, plususer.seed(0–99) anduser.is_logged_inparams.<key>andevent_namedevice.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_versionserver.country,server.billing_state,server.attribution.media_source,.campaign,.ad_set,.ad,.link_slugcomputed.minutes_since,hours_since,days_since,placements_in_hour,placements_in_day,placements_in_week,placements_in_monthorplacements_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:
| Outcome | Not gated | Gated |
|---|---|---|
| Any skip (holdout, no match…) | Runs | Runs |
| Purchased or restored | Runs | Runs |
| Declined | Runs | — |
| 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.
| Placement | When |
|---|---|
app_install | First launch |
app_launch | Every cold start |
session_start | Launch, or a return after over an hour away |
deep_link_open | Any deep link |
paywall_decline | A paywall was closed |
transaction_abandon | The store sheet was cancelled |
transaction_fail | The purchase failed |
survey_response | The cancel survey was answered |
touches_began | The 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.
Paywall behaviour
What a design in the editor can do beyond how it looks: conditions, states, tap actions, variables, surveys, trial reminders, theme tokens, fonts, transitions and the Android back button.
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.