@superwall/cli 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +201 -0
  3. package/dist/actions-MB-eBY64.js +140 -0
  4. package/dist/api-BF7-toqM.js +151 -0
  5. package/dist/api-output-B5hh0q4V.js +20 -0
  6. package/dist/app-K6j9Es7h.js +189 -0
  7. package/dist/asc-CArSwo5D.js +539 -0
  8. package/dist/asc-products-YQ6Oc6YO.js +93 -0
  9. package/dist/auth-CY2cO_NF.js +139 -0
  10. package/dist/auth.d.ts +30 -0
  11. package/dist/auth.js +4 -0
  12. package/dist/billing-DWyfEQ6l.js +80 -0
  13. package/dist/bind-hslFhcTR.js +213 -0
  14. package/dist/chunk-DQxbwPpZ.js +30 -0
  15. package/dist/command-Kwx4ekbo.js +283 -0
  16. package/dist/create-Bbi8BOO1.js +410 -0
  17. package/dist/dev-D0lQDCQI.js +397 -0
  18. package/dist/devtools-8EgLo86w.js +3638 -0
  19. package/dist/doctor-ByeRdMcl.js +88 -0
  20. package/dist/drivers-DVAZgone.js +413 -0
  21. package/dist/entry.d.ts +9 -0
  22. package/dist/entry.js +495 -0
  23. package/dist/existing-CcJrIIAU.js +88 -0
  24. package/dist/feedback-Z0Wk7VC5.js +73 -0
  25. package/dist/git-3OX9u3xE.js +433 -0
  26. package/dist/hosted-CHwaUqLd.js +32 -0
  27. package/dist/integrate-DqOAqK7J.js +863 -0
  28. package/dist/json-C3hPIMkI.js +7 -0
  29. package/dist/login-Dr8UN_Gx.js +290 -0
  30. package/dist/migrate-D92bJTg6.js +114 -0
  31. package/dist/org-B2gy9Pmu.js +40 -0
  32. package/dist/params-Bvq0iqQK.js +52 -0
  33. package/dist/pipeline-CHHIg6BU.js +1056 -0
  34. package/dist/print-skill-BnZAk7dV.js +74 -0
  35. package/dist/promote-CRe9170G.js +88 -0
  36. package/dist/publish-DsODvrOD.js +35 -0
  37. package/dist/push-BDkZUC0v.js +35 -0
  38. package/dist/query-DIllrSnk.js +53 -0
  39. package/dist/resource-CdP1MDla.js +483 -0
  40. package/dist/resources-CVrWwA1K.js +233 -0
  41. package/dist/run-cGGBUMs5.js +89 -0
  42. package/dist/scan-BQexuUPO.js +236 -0
  43. package/dist/skills-DhuUs28u.js +64 -0
  44. package/dist/skills-xrfXt9u0.js +205 -0
  45. package/dist/spawn-DSoTXy_j.js +69 -0
  46. package/dist/spinner-gOxIMz-V.js +18 -0
  47. package/dist/storekit-Ddvs4Ynw.js +29 -0
  48. package/dist/telemetry-CcfrtXdf.js +204 -0
  49. package/dist/token-DHRH8cxi.js +102 -0
  50. package/dist/ui-C4ncRJqd.js +27703 -0
  51. package/dist/update-BiVeR024.js +137 -0
  52. package/dist/upgrade-DYWspApv.js +72 -0
  53. package/package.json +87 -0
  54. package/prompts/actions/dashboard-setup.xml +10 -0
  55. package/prompts/actions/integrate.xml +5 -0
  56. package/prompts/actions/migrate.xml +11 -0
  57. package/prompts/actions/placements-implement.xml +20 -0
  58. package/prompts/actions/placements-review.xml +18 -0
  59. package/prompts/actions/review-fix.xml +18 -0
  60. package/prompts/actions/review.xml +18 -0
  61. package/prompts/commandments.xml +17 -0
  62. package/prompts/context.xml +9 -0
  63. package/skills/README.md +118 -0
  64. package/skills/superwall-dashboard/SKILL.md +81 -0
  65. package/skills/superwall-dashboard/references/setup.md +101 -0
  66. package/skills/superwall-integrate/SKILL.md +76 -0
  67. package/skills/superwall-integrate/references/expo.md +269 -0
  68. package/skills/superwall-integrate/references/flutter.md +285 -0
  69. package/skills/superwall-integrate/references/ios.md +314 -0
  70. package/skills/superwall-integrate/references/react-native.md +245 -0
  71. package/skills/superwall-migrate/SKILL.md +83 -0
  72. package/skills/superwall-migrate/references/adapty.md +229 -0
  73. package/skills/superwall-migrate/references/qonversion.md +227 -0
  74. package/skills/superwall-migrate/references/revenuecat.md +414 -0
  75. package/skills/superwall-placements/SKILL.md +73 -0
  76. package/skills/superwall-placements/references/expo.md +161 -0
  77. package/skills/superwall-placements/references/flutter.md +139 -0
  78. package/skills/superwall-placements/references/ios.md +165 -0
  79. package/skills/superwall-placements/references/react-native.md +145 -0
  80. package/skills/superwall-placements/references/strategy.md +221 -0
  81. package/skills/superwall-review/SKILL.md +75 -0
  82. package/skills/superwall-review/references/expo.md +100 -0
  83. package/skills/superwall-review/references/flutter.md +99 -0
  84. package/skills/superwall-review/references/ios.md +108 -0
  85. package/skills/superwall-review/references/react-native.md +100 -0
@@ -0,0 +1,73 @@
1
+ ---
2
+ name: superwall-placements
3
+ description: Add or audit Superwall placements at meaningful feature gates and route them to campaigns. Use when adding, reviewing, or debugging where paywalls fire in iOS, Expo, React Native, or Flutter apps. Not for first-time SDK setup (superwall-integrate) or creating campaigns and products (superwall-dashboard).
4
+ ---
5
+
6
+ # Superwall placements
7
+
8
+ A **placement** is a named event you fire at a meaningful moment. You register it,
9
+ optionally with a `feature` callback. Superwall evaluates your dashboard campaign
10
+ on-device and decides - remotely - whether to show a paywall and whether the
11
+ feature is gated. Reading subscription state is fine; only avoid a hand-rolled local
12
+ gate where it would override a gate the campaign is meant to control.
13
+
14
+ The API is the easy part. The value of this skill is knowing _where_ to place
15
+ placements and _why_. Read the strategy playbook first, then your framework's
16
+ reference for the exact call.
17
+
18
+ ## Read the strategy playbook FIRST
19
+
20
+ `references/strategy.md` - the definitive, framework-agnostic guide to where
21
+ placements go and why. Read it before adding or auditing any placement. It covers:
22
+
23
+ - **The mental model** - register generously; let campaigns decide what presents.
24
+ Analytics bridges, fire-and-forget calls, and intentionally unrouted placements
25
+ are valid. Put work in a feature callback when that action should be remotely
26
+ gateable; subscription-state reads remain valid for app state and UI.
27
+ - **Common candidates** (`onboarding_complete`, feature gates, limit-reached,
28
+ upgrade entry, broad-reach lifecycle, win-back), selected for the actual app.
29
+ - **App-type playbook** - concrete placements for editors, fitness, productivity,
30
+ content, dating/social, and AI apps.
31
+ - **The audit method** - enumerate the paid surface first, then map surface →
32
+ placement and flag the gaps.
33
+ - **Gate depth** - hard gate (paid-only) vs soft/non-gated (upsell), and when each
34
+ is right.
35
+ - **Calibration** (no universal count) and **naming rules**.
36
+
37
+ ## Then read the framework reference
38
+
39
+ Exact API, gating semantics, placement examples, audit checklist, and pitfalls:
40
+
41
+ | Framework | Reference |
42
+ | ------------ | ---------------------------- |
43
+ | iOS / Swift | `references/ios.md` |
44
+ | Expo | `references/expo.md` |
45
+ | React Native | `references/react-native.md` |
46
+ | Flutter | `references/flutter.md` |
47
+
48
+ ## Placements need campaigns (`superwall` CLI, authenticated)
49
+
50
+ A placement cannot present a paywall until a campaign routes it in the dashboard:
51
+
52
+ - `superwall campaigns list --project <id> --app <id> --json` - existing campaigns and placements.
53
+ - `superwall campaigns create "<description>" <placement_name> --project <id> --app <id> --json` - create one with its required first placement.
54
+ - `superwall campaigns placement <campaignId> <placement_name> --project <id> --app <id> --json` - route another placement.
55
+
56
+ Analytics-only, future, and paused placements may intentionally remain unrouted.
57
+ For placements expected to present now, use one campaign per distinct paywall
58
+ surface - not one per trigger. Don't create duplicates.
59
+
60
+ ## Docs access
61
+
62
+ Superwall docs are agent-fetchable as markdown:
63
+
64
+ - **Discover pages:** `curl -sL https://superwall.com/docs/llms.txt` (index of all
65
+ pages) or a platform index like `https://superwall.com/docs/ios/llms.txt`.
66
+ - **Fetch a page:** append `.md` to any docs route and use `curl -sL` (follow
67
+ redirects), e.g. `curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`.
68
+ - Full-text dumps: `.../llms-full.txt` per platform.
69
+
70
+ Key pages: `feature-gating`, `sdk-reference/register`,
71
+ `dashboard/dashboard-campaigns/campaigns-placements`, and
72
+ `dashboard/dashboard-campaigns/campaigns-standard-placements` (the auto-registered
73
+ lifecycle placements).
@@ -0,0 +1,161 @@
1
+ # Superwall placements - Expo
2
+
3
+ > Read `references/strategy.md` first for _where_ placements go and _why_ (the
4
+ > core set, app-type playbook, audit method, gate depth). This file is the Expo API.
5
+
6
+ Expo uses the `expo-superwall` package. Placements are registered through the
7
+ `usePlacement` hook (not a direct `Superwall.shared.register` call). The app must
8
+ be wrapped in `SuperwallProvider`.
9
+
10
+ ## API
11
+
12
+ ```ts
13
+ import { usePlacement } from "expo-superwall";
14
+
15
+ function usePlacement(callbacks?: {
16
+ onPresent?: (paywallInfo: PaywallInfo) => void
17
+ onDismiss?: (paywallInfo: PaywallInfo, result: PaywallResult) => void
18
+ onSkip?: (reason: PaywallSkippedReason) => void
19
+ onError?: (error: string) => void
20
+ }): {
21
+ registerPlacement: (args: {
22
+ placement: string
23
+ params?: Record<string, any>
24
+ feature?: () => void
25
+ }) => Promise<void>
26
+ state: PaywallState // idle | presented | dismissed | skipped | error
27
+ }
28
+ ```
29
+
30
+ `registerPlacement` is async - `await` it. Gating configuration lives in the
31
+ dashboard; the `feature` callback is your gate. Lifecycle observation goes through
32
+ the hook's `callbacks`, not a handler argument.
33
+
34
+ ### Provider (once, at the app root)
35
+
36
+ ```tsx
37
+ import { SuperwallProvider } from "expo-superwall";
38
+
39
+ export default function App() {
40
+ return (
41
+ <SuperwallProvider apiKeys={{ ios: "YOUR_IOS_KEY", android: "YOUR_ANDROID_KEY" }}>
42
+ <RootNavigator />
43
+ </SuperwallProvider>
44
+ );
45
+ }
46
+ ```
47
+
48
+ Children render after configuration succeeds, so hooks used inside are safe to call.
49
+
50
+ ### Gated feature
51
+
52
+ ```tsx
53
+ import { usePlacement } from "expo-superwall";
54
+ import { Button } from "react-native";
55
+
56
+ function ExportButton() {
57
+ const { registerPlacement } = usePlacement({
58
+ onDismiss: (_info, result) => console.log("dismissed", result.type),
59
+ onSkip: (reason) => console.log("skipped", reason),
60
+ });
61
+
62
+ const onExport = async () => {
63
+ await registerPlacement({
64
+ placement: "unlock_export",
65
+ params: { source: "editor_toolbar" },
66
+ feature: () => exportDocument(), // runs only when access is granted
67
+ });
68
+ };
69
+
70
+ return <Button title="Export as PDF" onPress={onExport} />;
71
+ }
72
+ ```
73
+
74
+ ### Fire-and-forget
75
+
76
+ ```tsx
77
+ await registerPlacement({ placement: "onboarding_complete" });
78
+ ```
79
+
80
+ `params` values are available in campaign audience rules; keys starting with `$`
81
+ are reserved.
82
+
83
+ ## Feature-gating semantics
84
+
85
+ The `feature` callback is your gate. When it runs (per the paywall's Feature
86
+ Gating setting in the dashboard):
87
+
88
+ | Situation | Does `feature` run? |
89
+ | ---------------------------------------------------- | ------------------------------------------------- |
90
+ | No campaign matches | Yes, immediately (no network, no paywall) |
91
+ | User already subscribed | Yes, immediately, no paywall |
92
+ | Holdout / no audience match | Yes, immediately (per current subscription state) |
93
+ | Paywall shown, **Non-Gated**, dismissed | Yes - whether or not they paid |
94
+ | Paywall shown, **Gated**, dismissed without purchase | No - feature blocked |
95
+ | User purchases | Yes, after the transaction |
96
+
97
+ **Gated** = paid-only; **Non-Gated** = show paywall, let them through either way.
98
+ Same `registerPlacement` call for both; the dashboard decides.
99
+
100
+ ## Where to place - one realistic gate
101
+
102
+ Limit-reached on a `Pressable`:
103
+
104
+ ```tsx
105
+ function AddProjectButton({ count, freeLimit }: { count: number; freeLimit: number }) {
106
+ const { registerPlacement } = usePlacement();
107
+ const onPress = async () => {
108
+ if (count < freeLimit) return createProject();
109
+ await registerPlacement({ placement: "project_limit_reached", feature: createProject });
110
+ };
111
+ return <Pressable onPress={onPress}><Text>New project</Text></Pressable>;
112
+ }
113
+ ```
114
+
115
+ ## Audit checklist
116
+
117
+ - Find every call: `grep -rn "registerPlacement\|usePlacement" app/ src/`.
118
+ - When a placement intentionally controls access, paywalled work is passed as
119
+ `feature` rather than run after the `await` unconditionally.
120
+ - No outer subscription branch should prevent an intentionally remote gate from
121
+ using its feature callback. Status reads elsewhere are valid and require context.
122
+ - Names are stable and match presenting campaigns exactly; preserve intentional
123
+ analytics taxonomies and never rename for style alone.
124
+ - Cross-check placements expected to present now with `superwall campaigns list
125
+ --project <id> --app <id> --json`; analytics-only, future, and paused placements may be unrouted.
126
+ - `usePlacement` is only called inside components under `SuperwallProvider`.
127
+ - Obvious premium boundaries (upgrade buttons, gated actions, quota limits,
128
+ onboarding end) with no placement.
129
+
130
+ ## Dashboard routing
131
+
132
+ ```bash
133
+ superwall campaigns list --project <id> --app <id> --json
134
+ superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
135
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
136
+ ```
137
+
138
+ ## Pitfalls
139
+
140
+ - **Registering during render.** Call `registerPlacement` from an event handler
141
+ (`onPress`) or an effect - never in the component body, or it fires on every
142
+ render.
143
+ - **Missing `await`.** `registerPlacement` returns a Promise; without `await` you
144
+ can't sequence follow-up work and errors go unhandled. Prefer the hook callbacks
145
+ or a try/catch.
146
+ - **Using the hook outside the provider.** `usePlacement` requires a
147
+ `SuperwallProvider` ancestor; otherwise it won't be configured.
148
+ - **Re-creating callbacks noisily.** The `callbacks` object is fine to inline, but
149
+ put stable logic in named functions to avoid confusion when auditing.
150
+ - **Conflicting gates.** An outer entitlement check is a problem only when the same
151
+ action is intentionally controlled by the placement's feature callback.
152
+
153
+ ## Deeper docs
154
+
155
+ - Index: https://superwall.com/docs/expo/llms.txt
156
+ - usePlacement: https://superwall.com/docs/expo/sdk-reference/hooks/usePlacement
157
+ - Feature gating: https://superwall.com/docs/expo/quickstart/feature-gating
158
+ - Present first paywall: https://superwall.com/docs/expo/quickstart/present-first-paywall
159
+ - SuperwallProvider: https://superwall.com/docs/expo/sdk-reference/components/SuperwallProvider
160
+ - Presentation handler: https://superwall.com/docs/expo/guides/advanced/using-the-presentation-handler
161
+ - Deep links: https://superwall.com/docs/expo/guides/handling-deep-links
@@ -0,0 +1,139 @@
1
+ # Superwall placements - Flutter
2
+
3
+ > Read `references/strategy.md` first for _where_ placements go and _why_ (the core
4
+ > set, app-type playbook, audit method, gate depth). This file is the Flutter API.
5
+
6
+ ## API
7
+
8
+ ```dart
9
+ import 'package:superwallkit_flutter/superwallkit_flutter.dart';
10
+
11
+ Future<void> registerPlacement(
12
+ String placement, {
13
+ Map<String, Object>? params,
14
+ PaywallPresentationHandler? handler,
15
+ Function()? feature,
16
+ })
17
+ ```
18
+
19
+ Called as `Superwall.shared.registerPlacement(...)`. Async - `await` it. `params`
20
+ values are available in campaign audience rules; keys starting with `$` are
21
+ reserved and dropped. The `feature` callback is your gate; gating configuration
22
+ lives in the dashboard.
23
+
24
+ ### Gated feature
25
+
26
+ ```dart
27
+ await Superwall.shared.registerPlacement(
28
+ 'unlock_export',
29
+ params: {'source': 'editor_toolbar'},
30
+ feature: () {
31
+ exportDocument(); // runs only when access is granted
32
+ },
33
+ );
34
+ ```
35
+
36
+ ### Fire-and-forget
37
+
38
+ ```dart
39
+ await Superwall.shared.registerPlacement('onboarding_complete');
40
+ ```
41
+
42
+ ### With a presentation handler (lifecycle observation)
43
+
44
+ ```dart
45
+ final handler = PaywallPresentationHandler();
46
+ handler.onPresent((info) => debugPrint('presented ${info.name}'));
47
+ handler.onDismiss((info, result) => debugPrint('dismissed $result'));
48
+ handler.onError((error) => debugPrint('error $error'));
49
+ handler.onSkip((reason) => debugPrint('skipped $reason'));
50
+
51
+ await Superwall.shared.registerPlacement(
52
+ 'unlock_export',
53
+ handler: handler,
54
+ feature: () => exportDocument(),
55
+ );
56
+ ```
57
+
58
+ Keep gated work in `feature`; use the handler for analytics/UI only.
59
+
60
+ ## Feature-gating semantics
61
+
62
+ When the `feature` callback runs (per the paywall's Feature Gating setting in the
63
+ dashboard - editor → General → Feature Gating):
64
+
65
+ | Situation | Does `feature` run? |
66
+ | ---------------------------------------------------- | --------------------------------------------------- |
67
+ | No campaign matches | Yes, immediately (no network, no paywall) |
68
+ | User already subscribed | Yes, immediately (entitlement verified server-side) |
69
+ | Holdout / no audience match | Yes, immediately (per current subscription state) |
70
+ | Paywall shown, **Non-Gated**, dismissed | Yes - whether or not they paid |
71
+ | Paywall shown, **Gated**, dismissed without purchase | No - feature blocked |
72
+ | User purchases | Yes, after the transaction |
73
+
74
+ **Gated** = paid-only; **Non-Gated** = show paywall, let them through either way.
75
+ Same `registerPlacement` call for both; the dashboard decides.
76
+
77
+ ## Where to place - one realistic gate
78
+
79
+ `onTap` / `onPressed`, limit-reached:
80
+
81
+ ```dart
82
+ ElevatedButton(
83
+ onPressed: () async {
84
+ if (projects.length < freeLimit) {
85
+ createProject();
86
+ return;
87
+ }
88
+ await Superwall.shared.registerPlacement(
89
+ 'project_limit_reached',
90
+ feature: () => createProject(),
91
+ );
92
+ },
93
+ child: const Text('New project'),
94
+ )
95
+ ```
96
+
97
+ ## Audit checklist
98
+
99
+ - Find every call: `grep -rn "registerPlacement" lib/`.
100
+ - When a placement intentionally controls access, paywalled work is passed as
101
+ `feature` rather than run after the `await` unconditionally.
102
+ - No outer entitlement branch should prevent an intentionally remote gate from
103
+ using its feature callback. Entitlement reads elsewhere are valid and require
104
+ context.
105
+ - Names are stable and match presenting campaigns exactly; preserve intentional
106
+ analytics taxonomies and never rename for style alone.
107
+ - Cross-check placements expected to present now with `superwall campaigns list
108
+ --project <id> --app <id> --json`; analytics-only, future, and paused placements may be unrouted.
109
+ - Obvious premium boundaries (upgrade buttons, gated actions, quota limits,
110
+ onboarding end) with no placement.
111
+
112
+ ## Dashboard routing
113
+
114
+ ```bash
115
+ superwall campaigns list --project <id> --app <id> --json
116
+ superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
117
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
118
+ ```
119
+
120
+ ## Pitfalls
121
+
122
+ - **Registering inside `build`.** Never call `registerPlacement` from a widget's
123
+ `build` method - it re-fires on every rebuild. Call it from a callback
124
+ (`onPressed`/`onTap`) or a one-shot `initState`.
125
+ - **Missing `await`.** `registerPlacement` returns `Future<void>`; without `await`
126
+ errors go unhandled and follow-up work can't be sequenced.
127
+ - **Registering before configure.** Ensure `Superwall.configure(apiKey)` has run
128
+ before any `registerPlacement`; earlier calls are dropped.
129
+ - **Conflicting gates.** An outer entitlement check is a problem only when the same
130
+ action is intentionally controlled by the placement's feature callback.
131
+
132
+ ## Deeper docs
133
+
134
+ - Index: https://superwall.com/docs/flutter/llms.txt
135
+ - register: https://superwall.com/docs/flutter/sdk-reference/register
136
+ - Feature gating: https://superwall.com/docs/flutter/quickstart/feature-gating
137
+ - Presentation handler: https://superwall.com/docs/flutter/guides/advanced/using-the-presentation-handler
138
+ - Tracking subscription state: https://superwall.com/docs/flutter/quickstart/tracking-subscription-state
139
+ - Deep links: https://superwall.com/docs/flutter/guides/handling-deep-links
@@ -0,0 +1,165 @@
1
+ # Superwall placements - iOS / Swift
2
+
3
+ > Read `references/strategy.md` first for _where_ placements go and _why_ (the
4
+ > core set, app-type playbook, audit method, gate depth). This file is the iOS API.
5
+
6
+ ## API
7
+
8
+ ```swift
9
+ import SuperwallKit
10
+
11
+ // With gated feature (the common form)
12
+ public func register(
13
+ placement: String,
14
+ params: [String: Any]? = nil,
15
+ handler: PaywallPresentationHandler? = nil,
16
+ feature: @escaping () -> Void
17
+ )
18
+
19
+ // Fire-and-forget (no feature to gate)
20
+ public func register(
21
+ placement: String,
22
+ params: [String: Any]? = nil,
23
+ handler: PaywallPresentationHandler? = nil
24
+ )
25
+ ```
26
+
27
+ Called on the shared instance: `Superwall.shared.register(...)`. Synchronous - no
28
+ `await`. `params` values are available in campaign audience rules; keys starting
29
+ with `$` are reserved and dropped.
30
+
31
+ ### Gated feature
32
+
33
+ ```swift
34
+ Superwall.shared.register(placement: "unlock_export") {
35
+ // Runs only when access is granted (see semantics below).
36
+ self.exportDocument()
37
+ }
38
+ ```
39
+
40
+ ### Fire-and-forget (e.g. onboarding end, an upsell surface)
41
+
42
+ ```swift
43
+ Superwall.shared.register(placement: "onboarding_complete")
44
+ ```
45
+
46
+ ### Passing params for audience targeting
47
+
48
+ ```swift
49
+ Superwall.shared.register(
50
+ placement: "unlock_export",
51
+ params: ["source": "editor_toolbar", "doc_count": documents.count]
52
+ ) {
53
+ self.exportDocument()
54
+ }
55
+ ```
56
+
57
+ ## Feature-gating semantics
58
+
59
+ The `feature` closure is your gate. When it runs depends on the paywall's
60
+ **Feature Gating** setting (paywall editor → General → Feature Gating):
61
+
62
+ | Situation | Does `feature` run? |
63
+ | ---------------------------------------------------- | ------------------------------------------------------ |
64
+ | No campaign matches the placement | Yes, immediately (no network, no paywall) |
65
+ | User already subscribed / entitled | Yes, immediately, no paywall |
66
+ | Holdout group or no audience match | Yes, immediately (runs per current subscription state) |
67
+ | Paywall shown, **Non-Gated**, dismissed | Yes - access granted whether or not they paid |
68
+ | Paywall shown, **Gated**, dismissed without purchase | No - feature blocked |
69
+ | Paywall shown, user purchases | Yes, after the transaction completes |
70
+
71
+ So: **Gated** = paid-only feature; **Non-Gated** = show the paywall but let them
72
+ through either way (soft paywall / upsell). This is toggled in the dashboard, not
73
+ in code - the same `register` call works for both.
74
+
75
+ ## Presentation handler (optional lifecycle observation)
76
+
77
+ ```swift
78
+ let handler = PaywallPresentationHandler()
79
+ handler.onPresent { paywallInfo in print("presented", paywallInfo.name) }
80
+ handler.onDismiss { paywallInfo, result in print("dismissed", result) }
81
+ handler.onError { error in print("error", error) }
82
+ handler.onSkip { reason in
83
+ switch reason {
84
+ case .holdout(let experiment): print("holdout", experiment.id)
85
+ case .noAudienceMatch: print("no audience match")
86
+ case .placementNotFound: print("placement not on a campaign")
87
+ }
88
+ }
89
+
90
+ Superwall.shared.register(placement: "unlock_export", handler: handler) {
91
+ self.exportDocument()
92
+ }
93
+ ```
94
+
95
+ Use the handler for analytics/UI reactions only. Do **not** move the gated work
96
+ into `onDismiss` - the `feature` closure already handles gating correctly.
97
+
98
+ ## Where to place - one realistic gate
99
+
100
+ SwiftUI button action:
101
+
102
+ ```swift
103
+ Button("Export as PDF") {
104
+ Superwall.shared.register(placement: "unlock_export") {
105
+ exporter.exportPDF(document)
106
+ }
107
+ }
108
+ ```
109
+
110
+ Limit-reached gate:
111
+
112
+ ```swift
113
+ func addProject() {
114
+ guard projects.count >= freeLimit else { return createProject() }
115
+ Superwall.shared.register(placement: "project_limit_reached") {
116
+ createProject()
117
+ }
118
+ }
119
+ ```
120
+
121
+ ## Audit checklist
122
+
123
+ - Find every call: `grep -rn "register(placement:" Sources/ App/` (also older
124
+ `Superwall.shared.track` if migrating).
125
+ - When a placement intentionally controls access, the paywalled work is **inside**
126
+ the `feature` closure rather than after the call.
127
+ - No outer subscription branch should prevent an intentionally remote gate from
128
+ using its feature closure. Subscription reads elsewhere are valid and require
129
+ context.
130
+ - Names are stable and match presenting campaigns exactly; preserve intentional
131
+ analytics taxonomies and never rename for style alone.
132
+ - Cross-check placements expected to present now with `superwall campaigns list
133
+ --project <id> --app <id> --json`; analytics-only, future, and paused placements may be unrouted.
134
+ - Obvious premium entry points (upgrade buttons, gated exports, quota limits,
135
+ onboarding end) that have **no** placement.
136
+
137
+ ## Dashboard routing
138
+
139
+ A placement is inert without a campaign:
140
+
141
+ ```bash
142
+ superwall campaigns list --project <id> --app <id> --json
143
+ superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
144
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
145
+ ```
146
+
147
+ ## Pitfalls
148
+
149
+ - **Registering inside `body`/render.** Never call `register` from within a
150
+ SwiftUI `body` computed property - it re-fires on every re-render. Register from
151
+ a button action or `.onAppear`/`.task`.
152
+ - **Registering before `configure`.** Calls before `Superwall.configure(apiKey:)`
153
+ (typically in `App.init` / `AppDelegate`) are dropped. Configure first.
154
+ - **Conflicting gates.** An outer entitlement check is a problem only when the same
155
+ action is intentionally controlled by the placement's feature closure.
156
+ - **Waiting on the closure to fire.** The `feature` closure may run async (after a
157
+ purchase). Don't assume it runs synchronously before the next line.
158
+
159
+ ## Deeper docs
160
+
161
+ - Index: https://superwall.com/docs/ios/llms.txt
162
+ - register: https://superwall.com/docs/ios/sdk-reference/register
163
+ - Feature gating: https://superwall.com/docs/ios/quickstart/feature-gating
164
+ - Presentation handler: https://superwall.com/docs/ios/guides/advanced/using-the-presentation-handler
165
+ - Deep links: https://superwall.com/docs/ios/guides/handling-deep-links
@@ -0,0 +1,145 @@
1
+ # Superwall placements - React Native
2
+
3
+ > Read `references/strategy.md` first for _where_ placements go and _why_ (the core
4
+ > set, app-type playbook, audit method, gate depth). This file is the RN API.
5
+
6
+ The RN SDK (`@superwall/react-native-superwall`) registers placements via a single
7
+ options-object `register` call on the shared instance. (This is distinct from Expo,
8
+ which uses the `usePlacement` hook - see `references/expo.md` if the app uses
9
+ `expo-superwall`.)
10
+
11
+ ## API
12
+
13
+ ```ts
14
+ import Superwall from "@superwall/react-native-superwall";
15
+ import { PaywallPresentationHandler } from "@superwall/react-native-superwall";
16
+
17
+ async register(options: {
18
+ placement: string
19
+ params?: Record<string, any> | Map<string, any>
20
+ handler?: PaywallPresentationHandler
21
+ feature?: () => void
22
+ }): Promise<void>
23
+ ```
24
+
25
+ Called as `Superwall.shared.register({ ... })`. Async - `await` it. `params` values
26
+ are available in campaign audience rules; keys starting with `$` are reserved and
27
+ dropped. The `feature` callback is your gate; gating configuration lives in the
28
+ dashboard.
29
+
30
+ ### Gated feature
31
+
32
+ ```ts
33
+ await Superwall.shared.register({
34
+ placement: "unlock_export",
35
+ params: { source: "editor_toolbar" },
36
+ feature: () => exportDocument(), // runs only when access is granted
37
+ });
38
+ ```
39
+
40
+ ### Fire-and-forget
41
+
42
+ ```ts
43
+ await Superwall.shared.register({ placement: "onboarding_complete" });
44
+ ```
45
+
46
+ ### With a presentation handler (lifecycle observation)
47
+
48
+ ```ts
49
+ const handler = new PaywallPresentationHandler();
50
+ handler.onPresent((info) => console.log("presented", info.name));
51
+ handler.onDismiss((info, result) => console.log("dismissed", result));
52
+ handler.onError((error) => console.log("error", error));
53
+
54
+ await Superwall.shared.register({
55
+ placement: "unlock_export",
56
+ handler,
57
+ feature: () => exportDocument(),
58
+ });
59
+ ```
60
+
61
+ Keep gated work in `feature`; use the handler for analytics/UI only.
62
+
63
+ ## Feature-gating semantics
64
+
65
+ When the `feature` callback runs (per the paywall's Feature Gating setting in the
66
+ dashboard):
67
+
68
+ | Situation | Does `feature` run? |
69
+ | ---------------------------------------------------- | ------------------------------------------------- |
70
+ | No campaign matches | Yes, immediately (no network, no paywall) |
71
+ | User already subscribed | Yes, immediately, no paywall |
72
+ | Holdout / no audience match | Yes, immediately (per current subscription state) |
73
+ | Paywall shown, **Non-Gated**, dismissed | Yes - whether or not they paid |
74
+ | Paywall shown, **Gated**, dismissed without purchase | No - feature blocked |
75
+ | User purchases | Yes, after the transaction |
76
+
77
+ **Gated** = paid-only; **Non-Gated** = show paywall, let them through either way.
78
+ Same `register` call for both; the dashboard decides.
79
+
80
+ ## Where to place - one realistic gate
81
+
82
+ `onPress` on a `Pressable`, limit-reached:
83
+
84
+ ```tsx
85
+ function AddProjectButton({ count, freeLimit }: { count: number; freeLimit: number }) {
86
+ const onPress = async () => {
87
+ if (count < freeLimit) return createProject();
88
+ await Superwall.shared.register({
89
+ placement: "project_limit_reached",
90
+ feature: createProject,
91
+ });
92
+ };
93
+ return (
94
+ <Pressable onPress={onPress}>
95
+ <Text>New project</Text>
96
+ </Pressable>
97
+ );
98
+ }
99
+ ```
100
+
101
+ ## Audit checklist
102
+
103
+ - Find every call: `grep -rn "\.register(" src/ app/` and `Superwall.shared`.
104
+ - When a placement intentionally controls access, paywalled work is passed as
105
+ `feature` rather than run after the `await` unconditionally.
106
+ - No outer subscription branch should prevent an intentionally remote gate from
107
+ using its feature callback. Status reads elsewhere are valid and require context.
108
+ - Names are stable and match presenting campaigns exactly; preserve intentional
109
+ analytics taxonomies and never rename for style alone.
110
+ - Cross-check placements expected to present now with `superwall campaigns list
111
+ --project <id> --app <id> --json`; analytics-only, future, and paused placements may be unrouted.
112
+ - Obvious premium boundaries (upgrade buttons, gated actions, quota limits,
113
+ onboarding end) with no placement.
114
+
115
+ ## Dashboard routing
116
+
117
+ ```bash
118
+ superwall campaigns list --project <id> --app <id> --json
119
+ superwall campaigns create "Editor upgrade paywall" unlock_export --project <id> --app <id> --json
120
+ superwall campaigns placement <campaignId> another_placement --project <id> --app <id> --json
121
+ ```
122
+
123
+ ## Pitfalls
124
+
125
+ - **Registering during render.** Call `register` from an event handler or effect,
126
+ never in the component body - it would fire on every render.
127
+ - **Missing `await`.** `register` returns a Promise; without `await` errors go
128
+ unhandled and you can't sequence follow-up work. Use `await` in a try/catch or
129
+ attach the presentation handler.
130
+ - **Registering before `configure`.** Ensure `Superwall.configure(apiKey)` has run
131
+ (typically at app startup) before any `register`; earlier calls are dropped.
132
+ - **Conflicting gates.** An outer entitlement check is a problem only when the same
133
+ action is intentionally controlled by the placement's feature callback.
134
+
135
+ ## Deeper docs
136
+
137
+ - Index: https://superwall.com/docs/react-native/llms.txt
138
+ - register: https://superwall.com/docs/react-native/sdk-reference/register
139
+ - PaywallPresentationHandler: https://superwall.com/docs/react-native/sdk-reference/PaywallPresentationHandler
140
+ - subscriptionStatus: https://superwall.com/docs/react-native/sdk-reference/subscriptionStatus
141
+ - Deep links: https://superwall.com/docs/react-native/sdk-reference/handleDeepLink
142
+
143
+ Note: the RN docs index does not expose a standalone feature-gating page; the
144
+ semantics above are confirmed on the `register` reference. Confirm exact wording at
145
+ the register URL above if a detail is load-bearing.