Paywall experiment guide
How to preview, plan, launch, pause, and read a reusable paywall experiment.
Current default
calm_utility — “More detail, less typing.” — is compiled into the app and is the fail-safe default whenever no valid running experiment is assigned.
The second approved layout is clear_handoff — “Turn a messy night into a clear handoff.” RevenueCat and the stores remain the authority for products, prices, trials, checkout, and entitlements.
Run an experiment
- Open Paywall Experiments and enter the Conversion admin token.
- Select an existing experiment or choose New experiment; give every reusable app its own
app_idand experiment ID. - Keep it
draftwhile editing the two approved layouts, copy, weights, placement, and enrollment percentage. - Choose Preview exact plan, review the canonical plan and SHA-256 hash, then apply it.
- Change the state to
running, preview and apply a second reviewed plan to enroll new eligible installations. - Watch views, checkout intent, verified trials, and verified paid starts; pause immediately if the result is unsafe or unclear.
- Use a new experiment ID for new copy after exposure; an exposed experiment is deliberately immutable.
Start with a small enrollment, preserve a control, define the winning metric before launch, and never put price or trial claims into remote copy.
What the background Worker does
- HMAC-hashes the installation identity and assigns a variant deterministically, so the same installation stays in the same group.
- Rejects malformed configuration, invalid weights, commerce claims, stale plans, and client-forged purchase conversions.
- Accepts view and checkout-intent events from the assigned app; only verified RevenueCat receipts can count trials and subscriptions.
- Runs the durable RevenueCat receipt and Conversion Relay retry queues from the Worker scheduler.
- Uses the last locally validated sticky assignment while offline; a fresh install with no valid assignment uses the compiled
calm_utilitypaywall.
Reusable app checklist
Cloudflare
- Register a distinct lowercase
app_id. - Create app-specific experiment IDs and salts.
- Use the shared strict assignment/event contracts.
- Keep secrets in Cloudflare bindings, never HTML.
App build
- Compile only reviewed layouts and icons.
- Send the app ID, placement, installation ID, platform, and version.
- Render only schema-valid returned copy.
- Keep store commerce copy provider-owned.
Test before traffic
- Run
node server/test/paywall_experiment_test.mjs. - Run the Flutter paywall experiment widget tests for both variants, narrow width, and 200% text.
- Preview both bundled variants in the browser, then leave the production experiment in
draftuntil traffic allocation is approved. - Confirm the RevenueCat provider-origin webhook proof is fresh before treating trial or paid attribution as release evidence.