expo-revenuecat-superwall-integration

在 Expo 中集成 RevenueCat 和 Superwall

开始编写代码前，先确定由谁负责完成购买。保留应用现有的账户和恢复策略；集成付费墙不意味着可以更改购买的归属方。

检查并选择

阅读锁文件、Expo 配置、实际的应用根组件、身份验证协调器、现有的计费调用、产品目录和权益检查。通过项目的环境变量处理方式解析公开的 SDK 密钥；切勿将秘密 API 密钥或 Webhook 凭据嵌入客户端代码。

使用 references/architecture-decision-tree.md 作出选择：

• **由 RevenueCat 负责执行购买和管理权益：**使用 Superwall 的 CustomPurchaseControllerProvider、准确的 RevenueCat 购买 API，并将完整权益集同步到 Superwall 一次。随附的集成示例涵盖了此路径。
• **由 Superwall 或现有计费实现负责完成购买：**RevenueCat 可以通过 purchasesAreCompletedBy 进行观察。这是当前架构，并不只是已弃用的迁移变通方案。设置实际使用的 StoreKit 版本，并验证收据和权益的传递。绝不能让两个 SDK 都完成同一笔交易。

Expo Go 不是原生商店测试环境。使用项目的包管理器和 npx expo install，仅安装必需的包；只有确实需要覆盖默认值时才添加 expo-build-properties。不要为了迁就旧示例而将平台最低版本降到 Android 23／iOS 15.1。

实现约定

1. **只初始化一次。**在挂载调用 RevenueCat 的代码之前，先等待 RevenueCat 完成配置。复用现有的配置负责人，不要再添加一个。让 Superwall 的配置失败清晰可见。
2. **匹配展示的产品。**按产品、基础方案以及可选优惠来解析 Android 订阅。如果明确指定的优惠不可用，则应失败关闭并刷新付费墙，绝不要改用 defaultOption、第一个选项或通用购买 API。请参阅 references/android-base-plans-offers-and-pending.md。
3. **返回实际的商店结果。**区分已购买、已取消、待处理和失败。已完成扣款但权益未激活，是履约问题，并不能证明付款失败。限制功能使用并进行核对；绝不要为了修复履约问题而再次扣款。成功恢复后没有找到有效访问权限，也是正常情况。
4. 正确订阅并清理。addCustomerInfoUpdateListener 返回 void。使用 removeCustomerInfoUpdateListener 移除同一个回调。应在首次获取数据前注册监听器，并防止较旧的初始结果覆盖较新的事件。映射所有有效权益；网络故障不代表订阅已失效。
5. **为账户切换设置门控。**在两个系统中使用同一个不透明计费 ID。串行执行原生身份调用；清理 effect 无法取消这些调用。身份验证状态变化时递增身份版本，并在该版本完成同步前，阻止购买、恢复和功能操作。商店操作进行期间应推迟账户切换。已知账户之间直接使用 logIn(newId) 切换；只有产品允许时才创建匿名状态。
6. **谨慎执行恢复。**恢复操作应由用户触发。历史导入／恢复流程应使用已批准的检查点和 syncPurchasesForResult，而不是在挂载时或每次启动时同步。调用前应审查转移／别名行为。

references/implementation-playbook.md 将示例与应用外壳连接起来。这些是集成模式，不能替代身份验证系统。references/examples/app.example.tsx 和简单的 Router 外壳展示了仅为访客挂载的方式；经过身份验证的应用必须提供身份门控。

验证

将 SKILL_DIR 解析为此技能的安装目录，并单独传入应用：

python3 "$SKILL_DIR/scripts/validate_expo_setup.py" --project-root /path/to/app
python3 -m unittest discover -s "$SKILL_DIR/tests" -v
node --test "$SKILL_DIR/tests/billing-contracts.test.cjs"

扫描器返回的是静态清单，并不表示已具备提交或计费条件。它不会执行动态 Expo 配置，也不会导出环境变量。退出状态为零表示清单已完成，且没有缺少核心依赖；正则匹配到的内容并不能证明某个服务提供商已挂载或某个回调已运行。

针对应用已安装的 SDK，对适配后的示例进行类型检查；检查解析后的配置和合并后的原生清单，然后测试真实的开发版／商店沙盒构建。测试应涵盖：显式优惠不可用、重复挂载／卸载、初始获取与监听器竞态、A→B→A 账户切换、退出登录、购买取消／待处理／成功、无访问权限时恢复购买、购买后权益延迟生效、重新安装，以及后端身份。更全面的检查清单请参阅 references/testing-matrix.md 和 references/dashboard-checklist.md。

报告所选负责人、变更的文件、确切的软件包版本、实际运行的测试、手动操作的控制面板／商店步骤，以及尚未解决的所有权或履约问题。客户端 UI 权限控制不能替代服务端授权。

重点参考资料

• references/identity-and-restore-behaviour.md：账户／恢复购买策略调查。
• references/ios-uuid-appaccounttoken-and-server-notifications.md：服务端通知中的身份问题；请根据已安装 SDK 的行为进行验证。
• references/observability-and-entitlement-verification.md：遥测和验证。
• references/troubleshooting.md：故障调查。

于 2026-09-13 审查的主要契约：RevenueCat React Native API、Superwall 购买控制器、Superwall RevenueCat 集成和RevenueCat Expo 设置。

关于共享的原生身份／商店队列，请阅读身份协调。