integrating-superwall-expo

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

这项技能的用途

Superwall 的 Expo SDK（expo-superwall）基于原生模块，因此无法在 Expo Go 中使用，配置错误通常会导致“Cannot find native module 'SuperwallExpo'”。这项技能提供一套可靠、可重复的工作流程，用于：

• 在 Expo SDK 53+ 中正确安装和配置 expo-superwall
• 通过展示位（远程营销活动）展示付费墙并实现功能门控
• 管理用户及其属性，并同步订阅状态（包括 RevenueCat）
• 接入深度链接／网页结账，并排查常见集成问题

必须遵守的事项（先检查）

1. expo-superwall 要求使用 Expo SDK 53+。
2. 不支持 Expo Go。请使用 Expo 开发构建版本（npx expo run:ios|android 或 EAS dev client）。
3. 最低目标 OS 版本：
   • iOS 部署目标：15.1+
   • Android minSdkVersion：21+
4. Superwall 配置不会在热重载期间重新获取。修改仪表板设置（付费墙／产品／营销活动）后，请完全重启应用。

快速上手清单（复制／粘贴并勾选）

• 确认 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 进行验证

默认实现模式（推荐）

1) 安装和设置平台目标

按照 references/INSTALLATION.md 中的 Superwall 安装指南操作。

2) 在根组件中配置 Superwall

在应用顶层使用 <SuperwallProvider />（通常位于 App.tsx 或根布局中）。添加加载／错误处理组件，以便显示故障。

参见 references/CONFIGURATION.md 和 assets/snippets/App.tsx。

3) 通过展示位展示付费墙并对功能进行门控

使用 usePlacement hook 注册展示位。这是用于以下功能的“统一 API”：

• 展示付费墙
• 功能门控（根据仪表板中的“Gated/Non-Gated”运行 feature 回调）
• 在 React 中跟踪付费墙生命周期状态

参见 references/PLACEMENTS_AND_GATING.md。

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

• 用户登录时使用 useUser().identify(userId) 进行识别
• 使用 useUser().signOut() 登出
• 使用 useUser().update({ … }) 设置／合并属性（传入 null 可取消设置）

参见：

• references/USER_MANAGEMENT.md
• references/SUBSCRIPTION_STATUS.md

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

如果要从仪表板预览付费墙、通过深度链接展示由营销活动驱动的付费墙，或接入网页结账流程，请配置深度链接并将收到的 URL 转发给 Superwall。

参见 references/DEEP_LINKS.md。

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

如果要由 RevenueCat 管理购买，而由 Superwall 管理付费墙／实验，请使用 CustomPurchaseControllerProvider（基于 hooks 的方式），并将权益状态同步到 Superwall。

参见 references/REVENUECAT.md。

故障排查手册（遇到问题时使用）

如果遇到 Cannot find native module 'SuperwallExpo'，或付费墙始终不显示：

1. 运行设置检查器：
   • node {baseDir}/scripts/check-setup.mjs
2. 确认你使用的是开发构建，而不是 Expo Go。
3. 如果你在现有项目中添加了 expo-superwall，请重新生成原生目录：
   • npx expo prebuild --clean （请先备份任何手动修改的原生代码）
4. 添加原生模块后，重新构建开发客户端（使用 EAS 或本地构建）。
5. 根据需要清除缓存并重新安装依赖。

完整的排查清单：references/TROUBLESHOOTING.md。

在代码仓库中执行操作时的输出预期

将此技能应用于实际代码库时，优先采用少量且易于审查的更改：

• 更新 package.json 依赖项
• 更新 app.json / app.config.* 插件和平台目标
• 配置根级 Provider（App.tsx/RootLayout）
• 添加一个用于验证的简单“首次展示”屏幕/按钮
• 可选：添加 src/superwall/placements.ts 常量，以及用于同步 RevenueCat 状态的 src/superwall/sync.ts

附上一段简短的“如何在本地测试”说明（开发构建命令 + 要触发的 placement）。

参考索引（仅在需要时阅读）

• 安装和前置条件：references/INSTALLATION.md
• Provider 和选项：references/CONFIGURATION.md
• Placements、访问控制和展示结果：references/PLACEMENTS_AND_GATING.md
• 用户和属性：references/USER_MANAGEMENT.md
• 订阅状态：references/SUBSCRIPTION_STATUS.md
• 事件监听器和分析数据转发：references/EVENTS_ANALYTICS.md
• 深层链接、预览和 Web 结账：references/DEEP_LINKS.md
• RevenueCat 集成：references/REVENUECAT.md
• 调试：references/TROUBLESHOOTING.md
• StoreKit 测试：references/STOREKIT_TESTING.md
• 区域设置覆盖：references/LOCALE.md
• Bare RN + Expo 模块：references/BARE_REACT_NATIVE.md
• 迁移 / 兼容 API：references/MIGRATION_COMPAT.md