expo-revenuecat-superwall-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Expo RevenueCat plus Superwall Integration

Expo RevenueCat 与 Superwall 集成

Use this skill to add or repair a modern RevenueCat plus Superwall stack in a React Native Expo app.

使用此技能在React Native Expo应用中添加或修复现代化的RevenueCat与Superwall技术栈。

What this skill should do

此技能应完成的工作

Choose the correct monetisation architecture before editing code.
Integrate with the repository's existing app shell, auth layer, and state management.
Prefer safe, production-ready defaults over the shortest possible demo.
Leave the user with code changes plus a clear list of remaining dashboard, store, and testing steps.

在编写代码前选择正确的变现架构。
与仓库现有的应用框架、认证层和状态管理系统集成。
优先选择安全、可用于生产环境的默认配置，而非最简演示方案。
为用户留下代码变更记录，以及清晰的仪表盘、应用商店和测试剩余步骤清单。

Critical rules

核心规则

Treat this as an Expo development-build integration, not an Expo Go integration.
Target Expo SDK 53 or newer.
Target iOS deployment target 15.1 or newer and Android min SDK 23 or newer.
Use public SDK keys only in the client.
Configure RevenueCat exactly once.
Mount Superwall near the app root exactly once.
Use the same stable, non-guessable, non-PII user identifier in RevenueCat and Superwall when the product has authentication.
Never use email addresses as RevenueCat or Superwall user IDs.
Do not call
```
syncPurchases()
```
on every launch. Use it only for deliberate migration or account-recovery scenarios.
```
restorePurchases()
```
is user-triggered. Do not hide it inside startup code.
On Android, ensure the launch mode is
```
standard
```
or
```
singleTop
```
.
Prefer a full app restart after Superwall dashboard changes during Expo development.

将此视为Expo开发构建集成，而非Expo Go集成。
目标为Expo SDK 53或更高版本。
目标iOS部署版本为15.1或更高，Android最低SDK版本为23或更高。
仅在客户端使用公开SDK密钥。
仅配置一次RevenueCat。
仅在应用根节点附近挂载一次Superwall。
当产品包含认证功能时，在RevenueCat和Superwall中使用相同的稳定、不可猜测、非PII用户标识符。
切勿将电子邮件地址用作RevenueCat或Superwall的用户ID。
不要在每次启动时调用
```
syncPurchases()
```
，仅在刻意迁移或账户恢复场景中使用。
```
restorePurchases()
```
由用户触发，不要隐藏在启动代码中。
在Android平台，确保启动模式为
```
standard
```
或
```
singleTop
```
。
在Expo开发过程中，Superwall仪表盘变更后优先选择完全重启应用。

First actions

初始操作

Inspect the repository before editing:
- ```
package.json
```
- ```
app.json
```
  ,
```
app.config.js
```
  , or
```
app.config.ts
```
- ```
App.tsx
```
  or
```
app/_layout.tsx
```
- any existing auth provider
- any existing purchase, paywall, or entitlement code

Run the validator if Python is available:

```
python3 scripts/validate_expo_setup.py
```

python3 scripts/validate_expo_setup.py --project-root /path/to/app

Answer these six preflight questions before choosing code:
- Is the app login-first, login-optional, or guest-first
- Is there existing purchase completion logic already in the repo
- Does Google Play use multiple base plans or offers
- Are App Store Server Notifications, Google server notifications, webhooks, or backend attribution in scope
- Is the entitlement model single-tier or multi-tier
- Does the product need strict account ownership, or easy restore across account confusion

Open only the references you need:

Core workflow:
```
references/implementation-playbook.md
```

Architecture choice:

references/architecture-decision-tree.md

Identity and restores:

references/identity-and-restore-behaviour.md

Android offers:

references/android-base-plans-offers-and-pending.md

iOS UUID and server notifications:

references/ios-uuid-appaccounttoken-and-server-notifications.md

Observability and verification:

references/observability-and-entitlement-verification.md

Test planning:
```
references/testing-matrix.md
```
Dashboard alignment:
```
references/dashboard-checklist.md
```
Failure modes:
```
references/troubleshooting.md
```

编写代码前检查仓库内容：
- ```
package.json
```
- ```
app.json
```
  、
```
app.config.js
```
  或
```
app.config.ts
```
- ```
App.tsx
```
  或
```
app/_layout.tsx
```
- 任何现有的认证提供者
- 任何现有的购买、付费墙或权益相关代码

如果Python可用，运行验证工具：

```
python3 scripts/validate_expo_setup.py
```

或

python3 scripts/validate_expo_setup.py --project-root /path/to/app

选择代码前回答以下六个预检问题：
- 应用是登录优先、可选登录还是访客优先
- 仓库中是否已有现有的购买完成逻辑
- Google Play是否使用多个基础套餐或优惠
- App Store服务器通知、Google服务器通知、Webhook或后端归因是否在范围内
- 权益模型是单层级还是多层级
- 产品需要严格的账户所有权，还是跨账户的便捷恢复

仅打开所需的参考文档：

核心工作流：
```
references/implementation-playbook.md
```

架构选择：

references/architecture-decision-tree.md

身份与恢复行为：

references/identity-and-restore-behaviour.md

Android优惠：

references/android-base-plans-offers-and-pending.md

iOS UUID与服务器通知：

references/ios-uuid-appaccounttoken-and-server-notifications.md

可观测性与验证：

references/observability-and-entitlement-verification.md

测试规划：
```
references/testing-matrix.md
```
仪表盘对齐：
```
references/dashboard-checklist.md
```
故障模式：
```
references/troubleshooting.md
```

Architecture choice

架构选择

Default for most new Expo apps

大多数新Expo应用的默认方案

Choose Architecture A: CustomPurchaseControllerProvider when:

Superwall is the paywall surface.
RevenueCat is the purchase and entitlement source of truth.
The app does not already have its own mature purchase completion pipeline.
You want the cleanest modern Expo integration.

Use:

references/architecture-decision-tree.md

references/examples/monetization.shared.tsx

```
references/examples/app.example.tsx
```

references/examples/expo-router-layout.example.tsx

references/examples/custom-purchase-controller.android-offers.tsx

当满足以下条件时选择架构A：CustomPurchaseControllerProvider：

Superwall作为付费墙载体。
RevenueCat作为购买和权益的可信数据源。
应用尚未拥有自己成熟的购买完成流程。
你需要最简洁的现代化Expo集成方案。

使用以下参考：

references/architecture-decision-tree.md

references/examples/monetization.shared.tsx

```
references/examples/app.example.tsx
```

references/examples/expo-router-layout.example.tsx

references/examples/custom-purchase-controller.android-offers.tsx

Use the migration path when the repo already owns purchase completion

当仓库已拥有购买完成逻辑时使用迁移方案

Choose Architecture B: purchasesAreCompletedBy / observer-mode migration when:

The app already finishes transactions itself.
The user explicitly wants to keep existing IAP code.
You are layering RevenueCat analytics, entitlements, or dashboards onto an existing billing implementation.
You must import historical purchases carefully.

Use:

references/architecture-decision-tree.md

references/examples/observer-mode-migration.tsx

references/identity-and-restore-behaviour.md

当满足以下条件时选择架构B：purchasesAreCompletedBy / 观察者模式迁移：

应用已自行处理交易完成。
用户明确希望保留现有的IAP代码。
你需要在现有计费实现上叠加RevenueCat分析、权益或仪表盘功能。
你必须谨慎导入历史购买记录。

使用以下参考：

references/architecture-decision-tree.md

references/examples/observer-mode-migration.tsx

references/identity-and-restore-behaviour.md

Shared implementation workflow

通用实施工作流

1. Audit the repo

1. 审计仓库

Collect these facts before changing code:

Expo SDK version
package manager
router style: Expo Router or plain
```
App.tsx
```

whether

expo-superwall

react-native-purchases

, and

expo-build-properties

are already installed

current iOS deployment target and Android min SDK
whether the app has auth
whether the repo already has RevenueCat, Superwall, StoreKit, Google Play Billing, or
```
react-native-iap
```
code
whether the project already ships one-time products in addition to subscriptions

修改代码前收集以下信息：

Expo SDK版本
包管理器
路由类型：Expo Router或普通
```
App.tsx
```

是否已安装

expo-superwall

、

react-native-purchases

和

expo-build-properties

当前iOS部署版本和Android最低SDK版本
应用是否包含认证功能
仓库中是否已有RevenueCat、Superwall、StoreKit、Google Play Billing或
```
react-native-iap
```
相关代码
项目是否除订阅外还售卖一次性产品

2. Align dashboards before deep code edits

2. 深度代码编辑前对齐仪表盘配置

Confirm the conceptual setup first:

RevenueCat project exists for iOS and Android
store products exist
entitlements exist
offerings exist where needed
Superwall project exists
Superwall public keys exist for both platforms
placements and campaigns exist
product IDs and entitlement IDs match the intended runtime mapping

Use

references/dashboard-checklist.md

先确认概念性设置：

已为iOS和Android创建RevenueCat项目
应用商店产品已存在
权益已配置
按需创建了优惠方案
已创建Superwall项目
已获取双平台的Superwall公钥
已配置展示位置和营销活动
产品ID和权益ID与预期的运行时映射一致

参考

references/dashboard-checklist.md

。

3. Install only the packages you actually need

3. 仅安装实际需要的包

Base stack:

npx expo install expo-superwall react-native-purchases expo-build-properties

Optional only if the user explicitly wants RevenueCat UI screens such as a customer center:

npx expo install react-native-purchases-ui

Do not add

react-native-purchases-ui

just because RevenueCat is installed.

基础技术栈：

npx expo install expo-superwall react-native-purchases expo-build-properties

仅当用户明确需要RevenueCat UI界面（如客户中心）时才安装可选包：

npx expo install react-native-purchases-ui

不要仅因为安装了RevenueCat就添加

react-native-purchases-ui

。

4. Update Expo config

4. 更新Expo配置

Add or repair

expo-build-properties

and set platform minimums. Preserve the repository's config style and existing plugins.

添加或修复

expo-build-properties

并设置平台最低版本。保留仓库的配置风格和现有插件。

5. Configure RevenueCat once

5. 配置RevenueCat一次

Use the correct public key for the current platform.
Configure once on startup.
If the app always requires a known user ID, prefer configuring with that ID instead of creating an anonymous state first.
If the app allows guests, configure without an App User ID and later call
```
logIn()
```
when auth resolves.

使用当前平台的正确公钥。
在启动时配置一次。
如果应用始终需要已知用户ID，优先使用该ID配置，而非先创建匿名状态。
如果应用允许访客，先不配置App User ID，待认证完成后调用
```
logIn()
```
。

6. Mount providers once near the root

6. 在根节点附近挂载一次提供者

For Architecture A, the normal order is:

configure RevenueCat
mount
```
CustomPurchaseControllerProvider
```
mount
```
SuperwallProvider
```
show
```
SuperwallLoading
```
render the app inside
```
SuperwallLoaded
```
mount one subscription sync component inside the loaded tree

对于架构A，正常顺序为：

配置RevenueCat
挂载
```
CustomPurchaseControllerProvider
```
挂载
```
SuperwallProvider
```
显示
```
SuperwallLoading
```
在
```
SuperwallLoaded
```
内渲染应用
在已加载的树中挂载一个订阅同步组件

7. Sync RevenueCat entitlements into Superwall

7. 将RevenueCat权益同步到Superwall

When Superwall is not directly owning purchase state, map RevenueCat entitlements into

setSubscriptionStatus

Fetch
```
CustomerInfo
```
on launch or when premium UI opens.
Subscribe to
```
addCustomerInfoUpdateListener
```
.
Map active entitlement IDs into Superwall entitlements.
Prefer syncing the full entitlement set, not just a boolean.

当Superwall不直接管理购买状态时，将RevenueCat权益映射到

setSubscriptionStatus

。

在启动时或高级UI打开时获取
```
CustomerInfo
```
。
订阅
```
addCustomerInfoUpdateListener
```
。
将活跃权益ID映射到Superwall权益。
优先同步完整的权益集合，而非仅布尔值。

8. Sync identities deliberately

8. 谨慎同步身份信息

Reuse the app's real auth state.
For login-first apps, prefer configuring RevenueCat with a custom App User ID from the start.
For guest-first apps, configure anonymously, then on login call
```
Purchases.logIn(userId)
```
and
```
identify(userId)
```
.
If switching from one known account to another, call
```
logIn(newUserId)
```
directly. Do not force a pointless logout first.
Only call
```
logOut()
```
if the product truly supports an anonymous post-logout state.

See

references/identity-and-restore-behaviour.md

and

references/examples/auth-sync.example.tsx

复用应用的真实认证状态。
对于登录优先的应用，优先从一开始就使用自定义App User ID配置RevenueCat。
对于访客优先的应用，先匿名配置，登录时调用
```
Purchases.logIn(userId)
```
和
```
identify(userId)
```
。
如果从一个已知账户切换到另一个，直接调用
```
logIn(newUserId)
```
，无需先执行无意义的登出操作。
仅当产品真正支持登出后的匿名状态时才调用
```
logOut()
```
。

参考

references/identity-and-restore-behaviour.md

和

references/examples/auth-sync.example.tsx

。

9. Register placements from premium entry points

9. 从高级入口点注册展示位置

Use business-action placement names such as
```
upgrade_pro
```
,
```
remove_limits
```
, or
```
export_pdf
```
.
Prefer placement-driven gating and dashboard audiences over hard-coded paywall branching.
Use
```
getPresentationResult()
```
only when you need to inspect what Superwall would do before presenting.

使用业务动作相关的展示位置名称，如
```
upgrade_pro
```
、
```
remove_limits
```
或
```
export_pdf
```
。
优先使用展示位置驱动的权限控制和仪表盘受众分组，而非硬编码的付费墙分支逻辑。
仅当需要在展示前检查Superwall的操作时才使用
```
getPresentationResult()
```
。

10. Add observability

10. 添加可观测性

Forward Superwall events into the app's analytics pipeline.
Keep debug logs enabled in development only.
Consider checking RevenueCat trusted entitlement verification in high-risk apps.

See

references/observability-and-entitlement-verification.md

将Superwall事件转发到应用的分析管道。
仅在开发环境中启用调试日志。
对于高风险应用，考虑启用RevenueCat可信权益验证。

参考

references/observability-and-entitlement-verification.md

。

11. Test with a matrix, not one happy path

11. 使用测试矩阵而非单一成功路径

Always verify:

cold start on iOS and Android
purchase success
cancel flow
pending flow where relevant
restore
guest to logged-in transition
account switch
reinstall
dashboard changes after a full restart
entitlement unlock in UI
webhook or server-notification identity consistency when relevant

Use

references/testing-matrix.md

务必验证以下场景：

iOS和Android冷启动
购买成功
取消流程
相关的待处理流程
恢复操作
访客到登录状态的转换
账户切换
重新安装
完全重启后的仪表盘变更
UI中的权益解锁
相关场景下Webhook或服务器通知的身份一致性

参考

references/testing-matrix.md

。

What to avoid

需避免的操作

Do not use
```
expo-superwall/compat
```
for new work.
Do not promise real Superwall support inside Expo Go.
Do not call
```
restorePurchases()
```
automatically during startup.
Do not call
```
syncPurchases()
```
on every launch.
Do not use emails, IDFA, device IDs, or hardcoded strings as billing IDs.
Do not leave duplicate purchase flows in place.
Do not ship Android API 21 just because Superwall alone supports it; the combined stack needs Android 23 or newer.

新开发工作不要使用
```
expo-superwall/compat
```
。
不要承诺在Expo Go内提供完整的Superwall支持。
不要在启动时自动调用
```
restorePurchases()
```
。
不要在每次启动时调用
```
syncPurchases()
```
。
不要将电子邮件、IDFA、设备ID或硬编码字符串用作计费ID。
不要保留重复的购买流程。
不要仅因为Superwall单独支持就发布Android API 21版本；整个技术栈需要Android 23或更高版本。

Final answer expectations

最终输出要求

When you finish editing a repo, your response should include:

the files changed
the chosen architecture and why
any manual RevenueCat, Superwall, App Store Connect, or Play Console steps still required
any assumptions about entitlements, product IDs, placements, restore behaviour, or account model
any migration debt intentionally left in place
how to run and test the development build

完成仓库编辑后，你的回复应包含：

修改的文件
选择的架构及原因
仍需手动完成的RevenueCat、Superwall、App Store Connect或Play Console步骤
关于权益、产品ID、展示位置、恢复行为或账户模型的任何假设
有意保留的任何迁移债务
如何运行和测试开发构建