Placement-by-placement product behavior

iOS Paywall & Gate Plan

Prepared 18 July 2026 · product requirements normalized from the placement artifact, current implementation status, and founder requirements

Design contract

Use the Midnight Studio system from the supplied artifact: four full-page decision moments and contextual bottom sheets at the exact tap. All surfaces route through one paywall coordinator and one pending-action mechanism.

iOS responsibilities

Fetch server access at sign-in, launch, foreground, purchase, restore, and transaction update.
Render backend denial context and RevenueCat price/eligibility truth.
Never grant paid access locally after a server-authoritative Free response; use bounded optimistic UI only while webhook reconciliation is pending.
Resume the original user action exactly once after access activates.
Fail closed for spending/creation; fail gracefully for cached playback according to product policy.

Full-page paywalls

Placement	When	Primary story	Dismiss	Purchase outcome
Onboarding	After Wait/Listen, before main tabs	Frame Free, 3-day Plus trial, and Pro	Continue Free; may invoke 50% exit once	Complete onboarding after activation or free choice
Second/extra creation	Generation preflight returns no recurring/one-time credit	Keep creating beyond Free allowance	Offer ladder based on persisted stage	Retry original generation
Plan & Billing	Profile/Settings user action	Compare, upgrade, manage, restore	Close; no forced rescue by default	Refresh plan screen
Locked generated episode	User taps personal episode requiring Plus	Play the exact episode they chose	Return to detail; optional rescue	Play episode

Contextual gate sheets

Gate	Trigger	Required access	Resume action
Generation allowance	Recurring/one-time credit or duration denial	Tier/credit shown by backend	Submit adjusted or paid generation
Higher recurring allowance	User requests a schedule or generation beyond the weekly credits	Tier and remaining weekly credits returned by backend	Save or retry after valid access
Document attach	No upload capability, no credits, or file too large	Plus/Pro and matching limit	Open picker or choose smaller file
Remix	Free user taps Remix	Trial/Plus/Pro	Open prefilled Remix
Pro sources	User taps source monitoring/export/advanced tool	Pro	Open exact tool
Transcript	Free user opens transcript tab	Trial/Plus/Pro	Reveal transcript
Speed	Free selects >1×; Plus selects >1.5×	Plus for ≤1.5×; Pro for ≤2×	Apply selected speed
Soundscape	User selects locked extended/complete soundscape	Catalog-specific tier	Select soundscape
Explore time	Free weekly playback reaches 45 min + rollover	Trial/Plus/Pro	Resume selected content

Offer presentation flow

Coordinator requests backend offer state and RevenueCat placement offering.
Standard stage presents normal paywall. Close invokes RevenueCat 50% exit paywall once.
After exit close, dismiss all layers, report outcome, persist stage/cooldown.
At a later eligible gate, 50% is primary. Its close invokes 65% exit once.
65% close ends the flow. Never immediately re-present another modal.
Any purchase waits for entitlement activation, refreshes server snapshot, then resumes pending action.

Trial UI requirements

Only show “3 days free” when RevenueCat intro eligibility is eligible.
CTA and pinned footer show trial duration, renewal price, cadence, and renewal date semantics.
Trial timeline: Today unlocks; Day 2 reminder if opted in; Day 3 renews.
Reminder toggle actually schedules/cancels a local notification and reflects permission state.
Trial usage screen shows 1 recurring credit for the weekly window, 1 maximum during the 3-day trial, and the trial end.
On ineligible accounts, replace trial copy with standard price without layout gaps.

Feature UI gates

Playback speed selector visually disables values above plan; server/player policy rechecks before applying.
Transcript tab remains discoverable but locked for Free; do not fetch transcript content before access.
Remix button uses a paid badge and gate context.
Soundscape catalog is partitioned by basic/extended/complete metadata, not hardcoded index positions.
File picker preflights count and file size; errors distinguish capability, weekly credits, and bytes.
Explore shows remain browsable after time exhaustion; play taps open the time-limit sheet.
Generation UI shows remaining recurring and one-time balances separately.

Jump-notification surfaces

Nudge	Surface	Eligibility	Tap destination
Allowance 80% used	Create banner/card	Free; no dismissal cooldown	Plan paywall at generation placement
Weekly credit ready	Home card/inbox	Free with available credit	Create with quota context
Trial ending	In-app banner + opted-in local/push	Active trial, ~24h remaining	Plan & Billing
Locked feature discovered	One-time coachmark	First transcript/remix/soundscape lock	Contextual gate
50%/65% campaign	Home/inbox, never auto-modal	Backend offer-stage eligible	Eligible offering

Presentation safety rules

One monetization modal at a time; queue a pending placement until current sheet dismisses.
No auto-paywall while audio is playing, keyboard input is active, user is signing in, or a system purchase sheet is pending.
Direct feature taps may show a gate immediately; passive nudges require explicit tap.
Restore is always available from paywall and Plan & Billing.
Every sheet propagates color scheme and supports VoiceOver, Dynamic Type, Reduce Motion, and localized prices.

Settings/Profile subscription management

Plan & Billing is a first-class Settings/Profile destination, not only a paywall placement. It displays effective access and usage, opens plan comparison for Free users, opens Apple’s management sheet or RevenueCat Customer Center for App Store subscribers, supports restore, and refreshes after every plan change. Detailed screen states, upgrade/downgrade timing, error behavior, analytics, and QA are defined in the separate iOS Subscription Management IPRD.

iOS telemetry

Track placement, presentation style, required capability, current tier/phase, offering, offer stage, and quota reason.
Track paywall close separately from App Store purchase cancellation.
Track pending action created/resumed/abandoned.
Track local reminder opted in/scheduled/fired/canceled.
Forward custom-paywall impressions to RevenueCat experiments when custom renderer is used.

iOS acceptance matrix

Every placement is directly launchable in a debug screenshot/test harness.
All paywalls render on small/large iPhone, iPad, light/dark, Dynamic Type, and VoiceOver.
Purchase, pending, delayed webhook, restore, nothing-to-restore, offline, auth failure, and refund states are understandable.
No duplicate paywall appears from simultaneous client and backend denials.
Successful purchase resumes each initiating action exactly once.