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.
Everything here is saved with the design and reaches installed apps on their next config refresh. It runs in the page itself, with the same runtime on the canvas and on the phone, so Preview and the Test tab show what a phone will do.
Select a node for Show when, Dynamic values, States and On tap. Select nothing for the settings that belong to the whole paywall.
Show when, dynamic values and states
- Show when — the node appears only while a condition holds: a trial they can take, a returning visitor, an app version.
- Dynamic values — one property decided by a rule, such as the words or the background. Otherwise it keeps its own value. Where two rules hold, the lower one wins.
- States — a different look while something holds: background, text colour, border colour, opacity and the words. Up to six on a node. Every state that holds applies, later ones winning.
A condition compares a variable using equals, greater than, contains, starts with, is set or version at least, grouped as All of these or Any of these.
Variables
Write them in any text as {{ products.selected.price }}, or test them in a condition.
| Group | Examples |
|---|---|
products.selected.*, products.<slot>.* | price, raw_price, period, periodly, is_subscription, is_lifetime, per_day, per_week, per_month, per_year, trial_days, trial_period, trial_eligible, has_trial, save, save_percent, currency, identifier, exists |
products.* | selected_index, has_trial |
device.* | platform, app_version, os_version, locale, language, region, currency, interface_style, days_since_install, minutes_since_install, total_paywall_views, days_since_last_paywall_view, is_first_app_open, now, size_class, viewport_width, viewport_height, local_hour, local_weekday, uses_24h_clock, screen_width, screen_height, is_tablet, font_scale, is_low_power |
user.* | id, and any attribute the app set |
params.* | Params the app passed to the placement |
state.* | Your own variables, plus did_abandon_transaction and did_complete_transaction |
page.* | index, count |
el.<id>.* | A drawer's is_open, a carousel's index, an answer's value (a multiple choice also has label and count) |
device.* and user.* are read once each time the paywall opens. device.local_weekday runs from 0 for Sunday, and device.font_scale is 1 at the default text size.
Filters change a value: default, upcase, downcase, capitalize, round, plus, minus, times, divided_by, date, date_add, countdown, append, prepend, truncate, size. For example {{ user.first_name | default: 'there' }}.
Variables on the Screen tab declares your own: true/false, number or text, up to 30. They start again each time the paywall opens.
On tap
A list of actions, run in order. A button keeps its built-in job when the list is empty: a buy button buys, Close closes, and so on. A plan card always selects itself, and the list runs as well.
| Group | Actions |
|---|---|
| Selling | Purchase, Select a plan, Restore purchases, Buy on the web (else in the store) |
| Moving | Close the paywall, Go to a screen, Open a drawer, Close a drawer, Scroll to, Open a link, Show another paywall |
| State | Set a variable, Set a user attribute, Send an event, Wait (up to 10 seconds) |
| App | Custom action, Ask for a permission, Ask for a review |
| Logic | If… otherwise… |
Some carry branches: a purchase has If they buy, If they cancel and If it fails, a custom action has yes and no, a permission has granted and denied.
Open a link goes to the browser, inside the app, or as an app link. Ask for a permission covers notifications, tracking, camera, photos, location, microphone and contacts. Send an event arrives as paywall_web_<name>, so a design cannot forge a revenue event. A node can also set a Haptic and a Pressed look.
Custom actions
The action hands a name to your app. Without onCustomAction, it fails.
Growth.init({
// ...
onCustomAction: async (name, payload) => {
if (name === "start_referral") {
const code = await createReferral();
// values become {{ state.referral_code }} on the page. false runs "If it says no".
return { ok: true, values: { referral_code: code } };
}
return false;
},
});What the app needs installed
Native modules are optional. A haptic or review with its module missing does nothing, and a permission reads as denied. The paywall still works.
| Action | Needs |
|---|---|
| Haptics | expo-haptics |
| Ask for a review | expo-store-review |
| Open a link inside the app | expo-web-browser. Without it the link opens in the browser |
| Trial reminders, or asking for notifications | expo-notifications |
| Asking for tracking, camera, photos, location, contacts | expo-tracking-transparency, expo-camera, expo-image-picker, expo-location, expo-contacts |
| Asking for the microphone | expo-audio or expo-av |
A design checks capabilities before an action that needs the app. On a build that cannot do it, the action logs paywall_web_paywall_action_unsupported with the action's name, and the design carries on.
Settings for the whole paywall
On the Screen tab, with nothing selected.
As placed uses the placement's style. Popup is a centred card over the app. Push slides in from the side.
Closes is the default, and a hard paywall ignores the button. Runs actions can go back a screen or open an exit offer.
On lets it open without a load — see warming. Turn it off for a heavy, film-led design that should not hold memory before it is asked for.
Whether the feature behind the paywall waits for a purchase. Saved at once, not with the design. See Placements and campaigns.
Plays when a button or tap action moves to another screen, and in reverse going back. A Go to a screen action can set its own.
Colours with a light and a dark value. Type $name in any colour field and the paywall follows the phone's light or dark mode.
A .woff2 or .ttf file by its address, the name text uses it by, and a weight. Pick it under a text's Effects and more.
Notifications scheduled when someone starts a free trial from this paywall, a set number of days before it ends. They are only scheduled where the app already has notification permission, so ask with a tap action if it does not. No prices in the words. In a development build the days count as minutes, so you can see one without waiting.
One question with 2–8 answers, optionally Other with text, shown natively over the paywall when someone closes it without buying or right after they buy. Ask % of people samples. Skipping is always allowed. Answers arrive as paywall_survey_answered with survey, question, answer and other_text, and skips as paywall_survey_skipped.
Per-language wording — see AI in the editor.
The paywall editor
Build a paywall by moving things on a phone — screens, layers, spacing, live prices — and publish it without an app release. Every control, and what each one does.
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.