@superwall/cli 1.7.0 → 2.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.
- package/README.md +192 -52
- package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.js} +82 -76
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-B7ym3oVS.js → billing-C3Q8DBU2.js} +98 -28
- package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
- package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
- package/dist/client-BL0f_yGf.js +176 -0
- package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/create-BSfvpWoD.js +19 -0
- package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
- package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
- package/dist/doctor-BWqIYcMn.js +83 -0
- package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28072 -1134
- package/dist/environment-eBXjELoN.js +58 -0
- package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
- package/dist/held-CPve03KJ.js +16 -0
- package/dist/held-DgnTFMl3.js +1112 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-BCEH5q0U.js +53 -0
- package/dist/login-BPOONe7n.js +16 -0
- package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
- package/dist/lookup-rr1AkCJA.js +71 -0
- package/dist/migrate-C9X2Vz81.js +274 -0
- package/dist/notification-url-CV86qiKP.js +100 -0
- package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
- package/dist/org-BQQDo7wm.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-CRlU72cq.js +29 -0
- package/dist/playbook-DVMXN7fh.js +53 -0
- package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
- package/dist/promote-Da8xctzy.js +91 -0
- package/dist/push-BV-grvQg.js +22 -0
- package/dist/push-D6R9icWN.js +495 -0
- package/dist/registry-BYVD-_h6.js +10385 -0
- package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
- package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
- package/dist/scan-B88OlWOt.js +4 -0
- package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
- package/dist/scope-DV22_Ufm.js +198 -0
- package/dist/screenshot-file-tVBfUEIi.js +16 -0
- package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
- package/dist/server-C4f6ccUr.js +22 -0
- package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
- package/dist/session-B-Uz0cQ7.js +40 -0
- package/dist/session-BuvArt1j.js +6 -0
- package/dist/session-C4rbE3VS.js +796 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +85 -31
- package/dist/skills/superwall-framework/references/cli.md +58 -27
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +64 -9
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/skills-CLGJuMnF.js +14 -0
- package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-C2U6QBJ9.js +294 -0
- package/dist/storage-6h9vyiAz.js +31 -0
- package/dist/storage-CerJ5KLP.d.ts +16 -0
- package/dist/storekit-CK9JmM2D.js +16 -0
- package/dist/storekit-CinJra3V.js +47 -0
- package/dist/telemetry-DKyDhURo.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
- package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
- package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
- package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/tools-skills/mobile-design/SKILL.md +447 -0
- package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
- package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
- package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
- package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/tools-skills/superwall/SKILL.md +263 -0
- package/dist/tools-skills/superwall/references/api.md +303 -0
- package/dist/tools-skills/superwall/references/asa.md +166 -0
- package/dist/tools-skills/superwall/references/asc.md +95 -0
- package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
- package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
- package/dist/tools-skills/superwall/references/docs.md +51 -0
- package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
- package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
- package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
- package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
- package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
- package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
- package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
- package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
- package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
- package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
- package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
- package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
- package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
- package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
- package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
- package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
- package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
- package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
- package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
- package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
- package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
- package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
- package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
- package/dist/tools-skills/superwall-editor/references/design.md +51 -0
- package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
- package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/tools-skills/wwdc/SKILL.md +22 -0
- package/dist/tools-skills/wwdc/references/docs.md +52 -0
- package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11360 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-DPo0a4Es.js +117 -0
- package/dist/upgrade-ffseQDMx.js +7 -0
- package/package.json +10 -5
- package/dist/api-CZzirVMj.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-DH6U8yuI.js +0 -190
- package/dist/asa-C-sQzPPn.js +0 -1194
- package/dist/asc-1ZBJ6DwS.js +0 -778
- package/dist/auth-YRhlV3DE.js +0 -140
- package/dist/billing-CCYHdApx.js +0 -80
- package/dist/bundle-id-CKxl_026.js +0 -121
- package/dist/command-CMIz81Da.js +0 -301
- package/dist/dev-DZy6pOnB.js +0 -22
- package/dist/doctor-H-hf-Yww.js +0 -88
- package/dist/feedback-CKf-rpBW.js +0 -152
- package/dist/hosted-CXe9TrWx.js +0 -32
- package/dist/migrate-C9ERDR6y.js +0 -284
- package/dist/org-sj7uyvp-.js +0 -40
- package/dist/output-C4o2gJ1K.js +0 -146
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-BqzqZhX1.js +0 -977
- package/dist/print-skill-ZojRSybs.js +0 -74
- package/dist/promote-BG8X4Nv_.js +0 -88
- package/dist/publish-sxLh-G4G.js +0 -35
- package/dist/push-bQ6Vxtg8.js +0 -35
- package/dist/query-_FbybaH-.js +0 -53
- package/dist/resource-CGIwSd29.js +0 -323
- package/dist/revenue-provider-ebsRINY8.js +0 -100
- package/dist/scope-BvzD-kO4.js +0 -223
- package/dist/skills-D_R-lEsK.js +0 -64
- package/dist/spinner-TWa0hia6.js +0 -18
- package/dist/storekit-Cj9Cpjcz.js +0 -29
- package/dist/telemetry-DeA1mvnT.js +0 -169
- package/dist/ui-Dy0b-9L8.js +0 -27738
- package/dist/update-B2fWIc4q.js +0 -59
- package/dist/upgrade-BmzkTKrh.js +0 -72
- /package/dist/{devtools-8EgLo86w.js → devtools-pBl_vt03.js} +0 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# Superwall placements - Expo
|
|
2
|
+
|
|
3
|
+
> Read `strategy.md` (beside this file) 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 `strategy.md` (beside this file) 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 `strategy.md` (beside this file) 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,69 @@
|
|
|
1
|
+
# Superwall placements
|
|
2
|
+
|
|
3
|
+
A **placement** is a named event you fire at a meaningful moment. You register it,
|
|
4
|
+
optionally with a `feature` callback. Superwall evaluates your dashboard campaign
|
|
5
|
+
on-device and decides - remotely - whether to show a paywall and whether the
|
|
6
|
+
feature is gated. Reading subscription state is fine; only avoid a hand-rolled local
|
|
7
|
+
gate where it would override a gate the campaign is meant to control.
|
|
8
|
+
|
|
9
|
+
The API is the easy part. The value of this skill is knowing _where_ to place
|
|
10
|
+
placements and _why_. Read the strategy playbook first, then your framework's
|
|
11
|
+
reference for the exact call.
|
|
12
|
+
|
|
13
|
+
## Read the strategy playbook FIRST
|
|
14
|
+
|
|
15
|
+
`strategy.md` (beside this file) - the definitive, framework-agnostic guide to where
|
|
16
|
+
placements go and why. Read it before adding or auditing any placement. It covers:
|
|
17
|
+
|
|
18
|
+
- **The mental model** - register generously; let campaigns decide what presents.
|
|
19
|
+
Analytics bridges, fire-and-forget calls, and intentionally unrouted placements
|
|
20
|
+
are valid. Put work in a feature callback when that action should be remotely
|
|
21
|
+
gateable; subscription-state reads remain valid for app state and UI.
|
|
22
|
+
- **Common candidates** (`onboarding_complete`, feature gates, limit-reached,
|
|
23
|
+
upgrade entry, broad-reach lifecycle, win-back), selected for the actual app.
|
|
24
|
+
- **App-type playbook** - concrete placements for editors, fitness, productivity,
|
|
25
|
+
content, dating/social, and AI apps.
|
|
26
|
+
- **The audit method** - enumerate the paid surface first, then map surface →
|
|
27
|
+
placement and flag the gaps.
|
|
28
|
+
- **Gate depth** - hard gate (paid-only) vs soft/non-gated (upsell), and when each
|
|
29
|
+
is right.
|
|
30
|
+
- **Calibration** (no universal count) and **naming rules**.
|
|
31
|
+
|
|
32
|
+
## Then read the framework reference
|
|
33
|
+
|
|
34
|
+
Exact API, gating semantics, placement examples, audit checklist, and pitfalls:
|
|
35
|
+
|
|
36
|
+
| Framework | Reference |
|
|
37
|
+
| ------------ | ---------------------------- |
|
|
38
|
+
| iOS / Swift | `ios.md` (beside this file) |
|
|
39
|
+
| Expo | `expo.md` (beside this file) |
|
|
40
|
+
| React Native | `react-native.md` (beside this file) |
|
|
41
|
+
| Flutter | `flutter.md` (beside this file) |
|
|
42
|
+
| Android | `android.md` (beside this file) |
|
|
43
|
+
|
|
44
|
+
## Placements need campaigns (`superwall` CLI, authenticated)
|
|
45
|
+
|
|
46
|
+
A placement cannot present a paywall until a campaign routes it in the dashboard:
|
|
47
|
+
|
|
48
|
+
- `superwall campaigns list --project <id> --app <id> --json` - existing campaigns and placements.
|
|
49
|
+
- `superwall campaigns create "<description>" <placement_name> --project <id> --app <id> --json` - create one with its required first placement.
|
|
50
|
+
- `superwall campaigns placement <campaignId> <placement_name> --project <id> --app <id> --json` - route another placement.
|
|
51
|
+
|
|
52
|
+
Analytics-only, future, and paused placements may intentionally remain unrouted.
|
|
53
|
+
For placements expected to present now, use one campaign per distinct paywall
|
|
54
|
+
surface - not one per trigger. Don't create duplicates.
|
|
55
|
+
|
|
56
|
+
## Docs access
|
|
57
|
+
|
|
58
|
+
Superwall docs are agent-fetchable as markdown:
|
|
59
|
+
|
|
60
|
+
- **Discover pages:** `curl -sL https://superwall.com/docs/llms.txt` (index of all
|
|
61
|
+
pages) or a platform index like `https://superwall.com/docs/ios/llms.txt`.
|
|
62
|
+
- **Fetch a page:** append `.md` to any docs route and use `curl -sL` (follow
|
|
63
|
+
redirects), e.g. `curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md`.
|
|
64
|
+
- Full-text dumps: `.../llms-full.txt` per platform.
|
|
65
|
+
|
|
66
|
+
Key pages: `feature-gating`, `sdk-reference/register`,
|
|
67
|
+
`dashboard/dashboard-campaigns/campaigns-placements`, and
|
|
68
|
+
`dashboard/dashboard-campaigns/campaigns-standard-placements` (the auto-registered
|
|
69
|
+
lifecycle placements).
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Superwall placements - React Native
|
|
2
|
+
|
|
3
|
+
> Read `strategy.md` (beside this file) 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 `expo.md` (beside this file) 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.
|