integrating-superwall-expo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrating Superwall in React Native Expo (expo-superwall)

在React Native Expo中集成Superwall（expo-superwall）

Why this skill exists

为何需要本技能

Superwall’s Expo SDK (

expo-superwall

) is native-module based, so Expo Go won’t work and setup mistakes often look like “Cannot find native module 'SuperwallExpo'”. This skill provides a reliable, repeatable workflow to:

install + configure
```
expo-superwall
```
correctly in Expo SDK 53+
present paywalls via placements (remote campaigns) and implement feature gating
manage users + attributes, and keep subscription status in sync (including RevenueCat)
wire deep links / web checkout, and troubleshoot the common integration failures

Superwall的Expo SDK（

expo-superwall

）基于原生模块开发，因此Expo Go无法兼容，且配置错误常表现为“Cannot find native module 'SuperwallExpo'”。本技能提供可靠、可复用的工作流，帮助你：

在Expo SDK 53+项目中正确安装并配置
```
expo-superwall
```
通过展示位（远程活动）展示付费墙并实现功能权限管控
管理用户及属性，保持订阅状态同步（包括集成RevenueCat的场景）
配置深度链接/网页结账，并排查常见的集成故障

Non‑negotiables (check first)

必查前提条件

Expo SDK 53+ is required for
```
expo-superwall
```
.
Expo Go is not supported. Use an Expo Development Build (
```
npx expo run:ios|android
```
or EAS dev client).
Target minimum OS versions:
- iOS deployment target: 15.1+
- Android minSdkVersion: 21+
Superwall config does not refetch during hot reload. After dashboard changes (paywalls/products/campaigns), fully restart the app.

**必须使用Expo SDK 53+**才能兼容
```
expo-superwall
```
。
不支持Expo Go，请使用Expo开发构建版本（
```
npx expo run:ios|android
```
或EAS开发客户端）。
目标系统最低版本要求：
- iOS部署目标：15.1+
- Android minSdkVersion：21+
Superwall配置不会在热重载时重新获取。在后台修改（付费墙/产品/活动）后，需完全重启应用。

Fast path checklist (copy/paste and tick)

快速实施清单（可复制粘贴并勾选）

Confirm Expo SDK version (>=53) and you are not using Expo Go
Install packages:
```
expo-superwall
```
(+
```
expo-build-properties
```
if needed)
Set iOS/Android minimum versions via
```
expo-build-properties
```

Wrap app with

<SuperwallProvider>

<SuperwallLoading/>

<SuperwallError/>

<SuperwallLoaded/>

)

usePlacement().registerPlacement({ placement: "…" })

(Optional) Implement feature gating via
```
feature: () => …
```
callback
(Optional) Identify user + set user attributes with
```
useUser()
```
(Optional) Sync subscription status (built-in, or manual when using RevenueCat/custom billing)
Rebuild dev client after native changes (
```
npx expo prebuild --clean
```
if needed)
Validate with:
```
node {baseDir}/scripts/check-setup.mjs
```

确认Expo SDK版本（≥53）且未使用Expo Go
安装依赖包：
```
expo-superwall
```
（如需可搭配
```
expo-build-properties
```
）
通过
```
expo-build-properties
```
设置iOS/Android最低版本

使用

<SuperwallProvider>

包裹应用（搭配

<SuperwallLoading/>

、

<SuperwallError/>

、

<SuperwallLoaded/>

组件）

通过

usePlacement().registerPlacement({ placement: "…" })

注册首个展示位

（可选）通过
```
feature: () => …
```
回调实现功能权限管控
（可选）使用
```
useUser()
```
识别用户并设置用户属性
（可选）同步订阅状态（内置同步，或使用RevenueCat/自定义计费时手动同步）
修改原生配置后重新构建开发客户端（必要时执行
```
npx expo prebuild --clean
```
）
通过以下命令验证配置：
```
node {baseDir}/scripts/check-setup.mjs
```

Default implementation pattern (recommended)

推荐的默认实现方案

1) Install + platform targets

1) 安装与平台版本配置

Follow the Superwall install guide in

references/INSTALLATION.md

遵循

references/INSTALLATION.md

中的Superwall安装指南。

2) Configure Superwall at the root

2) 在根节点配置Superwall

Use

<SuperwallProvider />

at the top of your app (typically in

App.tsx

or your root layout). Add loading/error handling components so failures are visible.

See

references/CONFIGURATION.md

and

assets/snippets/App.tsx

在应用顶层（通常是

App.tsx

或根布局文件）使用

<SuperwallProvider />

。添加加载/错误处理组件，以便及时发现故障。

详见

references/CONFIGURATION.md

和

assets/snippets/App.tsx

。

3) Present paywalls & gate features via placements

3) 通过展示位展示付费墙并管控功能

Use the

usePlacement

hook to register placements. This is the “one API” that powers:

presenting paywalls
feature gating (run
```
feature
```
callback depending on dashboard “Gated/Non‑Gated”)
tracking paywall lifecycle state in React

See

references/PLACEMENTS_AND_GATING.md

使用

usePlacement

钩子注册展示位。这是一个统一API，可实现：

展示付费墙
功能权限管控（根据后台“需授权/无需授权”设置执行
```
feature
```
回调）
在React中追踪付费墙生命周期状态

详见

references/PLACEMENTS_AND_GATING.md

。

4) Manage users, attributes, and subscription state

4) 管理用户、属性与订阅状态

Identify on login with
```
useUser().identify(userId)
```
Sign out with
```
useUser().signOut()
```
Set/merge attributes with
```
useUser().update({ … })
```
(pass
```
null
```
to unset)

See:

```
references/USER_MANAGEMENT.md
```
```
references/SUBSCRIPTION_STATUS.md
```

登录时通过
```
useUser().identify(userId)
```
识别用户
通过
```
useUser().signOut()
```
实现登出
通过
```
useUser().update({ … })
```
设置/合并属性（传入
```
null
```
可取消设置）

详见：

```
references/USER_MANAGEMENT.md
```
```
references/SUBSCRIPTION_STATUS.md
```

5) Deep links & web checkout (optional)

5) 深度链接与网页结账（可选）

If you want paywall previews from the dashboard, campaign-driven paywalls from deep links, or web checkout flows, wire deep links and forward incoming URLs to Superwall.

See

references/DEEP_LINKS.md

若需从后台预览付费墙、通过深度链接触发活动付费墙，或使用网页结账流程，请配置深度链接并将传入的URL转发给Superwall。

详见

references/DEEP_LINKS.md

。

6) RevenueCat (optional, recommended approach)

6) RevenueCat集成（可选，推荐方案）

If you want RevenueCat to own purchases while Superwall owns paywalls/experiments, use

CustomPurchaseControllerProvider

(hooks-based) and sync entitlement state to Superwall.

See

references/REVENUECAT.md

若希望由RevenueCat处理购买流程，同时由Superwall管理付费墙/实验，请使用

CustomPurchaseControllerProvider

（基于钩子）并将权益状态同步至Superwall。

详见

references/REVENUECAT.md

。

Troubleshooting playbook (use when things don’t work)

故障排查指南（遇到问题时使用）

If you hit Cannot find native module 'SuperwallExpo', or paywalls never show:

Run the setup checker:
- ```
node {baseDir}/scripts/check-setup.mjs
```
Confirm you’re on a dev build, not Expo Go.
If you added
```
expo-superwall
```
to an existing project, regenerate native folders:
- ```
npx expo prebuild --clean
```
  (backs up any manual native edits first)
Rebuild the dev client (EAS or local) after adding native modules.
Clear caches and reinstall deps as needed.

Full triage checklist:

references/TROUBLESHOOTING.md

若出现**Cannot find native module 'SuperwallExpo'**错误，或付费墙始终无法展示：

运行配置检查脚本：
- ```
node {baseDir}/scripts/check-setup.mjs
```
确认使用的是开发构建版本，而非Expo Go。
若在现有项目中添加
```
expo-superwall
```
，请重新生成原生文件夹：
- ```
npx expo prebuild --clean
```
  （会先备份所有手动修改的原生代码）
添加原生模块后重新构建开发客户端（EAS或本地构建）。
必要时清除缓存并重新安装依赖。

完整排查清单：

references/TROUBLESHOOTING.md

。

Output expectations when performing work in a repo

在代码仓库中实施本技能的输出要求

When applying this skill to a real codebase, prefer a small, reviewable set of changes:

```
package.json
```
dependency updates
```
app.json
```
/
```
app.config.*
```
plugin + platform target updates
Root provider wiring (
```
App.tsx
```
/RootLayout)
A small “first placement” screen/button for verification

Optional:

src/superwall/placements.ts

constants and

src/superwall/sync.ts

for RevenueCat status sync

Include a short “How to test locally” note (dev build commands + which placement to trigger).

在真实代码库中应用本技能时，建议提交少量便于评审的修改：

```
package.json
```
中的依赖更新
```
app.json
```
/
```
app.config.*
```
中的插件与平台版本更新
根节点Provider配置（
```
App.tsx
```
/RootLayout）
用于验证的小型“首个展示位”页面/按钮
可选：
```
src/superwall/placements.ts
```
常量文件和
```
src/superwall/sync.ts
```
（用于RevenueCat状态同步）

请附上简短的“本地测试说明”（开发构建命令及需触发的展示位）。

Reference map (read only when needed)

参考文档索引（按需查阅）

Install + prerequisites:
```
references/INSTALLATION.md
```
Provider + options:
```
references/CONFIGURATION.md
```
Placements, gating, presentation results:
```
references/PLACEMENTS_AND_GATING.md
```
Users + attributes:
```
references/USER_MANAGEMENT.md
```
Subscription state:
```
references/SUBSCRIPTION_STATUS.md
```
Event listeners + analytics forwarding:
```
references/EVENTS_ANALYTICS.md
```
Deep links, previews, web checkout:
```
references/DEEP_LINKS.md
```
RevenueCat integration:
```
references/REVENUECAT.md
```
Debugging:
```
references/TROUBLESHOOTING.md
```
StoreKit testing:
```
references/STOREKIT_TESTING.md
```
Locale override:
```
references/LOCALE.md
```
Bare RN + Expo modules:
```
references/BARE_REACT_NATIVE.md
```
Migration / compat API:
```
references/MIGRATION_COMPAT.md
```

安装与前提条件：
```
references/INSTALLATION.md
```
Provider与配置选项：
```
references/CONFIGURATION.md
```
展示位、权限管控、展示结果：
```
references/PLACEMENTS_AND_GATING.md
```
用户与属性：
```
references/USER_MANAGEMENT.md
```
订阅状态：
```
references/SUBSCRIPTION_STATUS.md
```
事件监听与分析转发：
```
references/EVENTS_ANALYTICS.md
```
深度链接、预览、网页结账：
```
references/DEEP_LINKS.md
```
RevenueCat集成：
```
references/REVENUECAT.md
```
调试：
```
references/TROUBLESHOOTING.md
```
StoreKit测试：
```
references/STOREKIT_TESTING.md
```
区域设置覆盖：
```
references/LOCALE.md
```
原生RN + Expo模块：
```
references/BARE_REACT_NATIVE.md
```
迁移/兼容API：
```
references/MIGRATION_COMPAT.md
```
",