revenuecat-testing-setup

revenuecat-testing-setup：为 RevenueCat 购买设置测试环境

当用户想要在不产生真实费用的情况下，针对 RevenueCat 测试购买时，请使用此技能。每个商店都有自己的测试渠道，且各渠道的保真度和迭代成本各不相同。

1. 检测平台

检查工作目录，并从上到下选择第一个匹配项：

1. React Native：package.json 中有 react-native-purchases 条目，或将 react-native 列为依赖项 → 阅读 platforms/react-native.md。如果 expo 也属于依赖项，请注明这是一个 Expo 项目。
2. Flutter：项目根目录中存在 pubspec.yaml → 阅读 platforms/flutter.md。
3. Kotlin Multiplatform：build.gradle.kts 中包含 kotlin { … } 多平台源集代码块，或依赖 com.revenuecat.purchases:purchases-kmp* → 阅读 platforms/kmp.md。
4. Android（原生）：build.gradle(.kts) 应用了 com.android.application（且不是 KMP）→ 阅读 platforms/android.md。
5. iOS（原生）：项目根目录中存在 Package.swift、*.xcodeproj、*.xcworkspace 或 Podfile → 阅读 platforms/ios.md。

如果有多个匹配项（例如 Flutter 项目中有一个 ios/ 文件夹），请选择最外层的项目，也就是拥有构建配置的项目。如果仍无法确定，请询问用户要配置哪个平台。

2. 通用概念（适用于所有平台）

开发期间无法收取真实费用

每个商店都有专门的测试渠道。选择合适的渠道取决于你要测试的内容。

测试渠道：保真度与迭代成本

保真度越高，越能覆盖真实购买流程；保真度越低，迭代速度越快。

• RevenueCat Test Store（保真度最低、迭代最快、结果确定）。 由 RevenueCat 托管的模拟商店。SDK 使用来自控制面板的 test_… API 密钥进行配置。购买时会打开 Test Store 对话框，你可以手动选择结果：购买成功、购买失败或取消。购买会触发权益、更新 CustomerInfo 并显示在控制面板中，但不会调用 Apple 或 Google。最适合调整付费墙、集成测试和 CI 冒烟测试。
• iOS StoreKit 配置文件（保真度较低、Apple 模拟环境）。 Xcode 在本地模拟商店。购买会立即成功，不会与 App Store Connect 往返通信。适用于需要测试特定 StoreKit 行为的情况。在此模式下，RevenueCat 交易可能会显示在控制面板中，也可能不会，具体取决于 SDK 版本和预期路由，因此不能忠实地用于控制面板测试。
• iOS Sandbox（真实沙盒 Apple ID）/ Android Internal Testing（许可测试员）。 使用真实商店后端，交易会真实导入 RevenueCat 控制面板，收据也是真实的。迭代较慢：需要构建、安装，并等待 Play 传播或 App Store Connect 注册产品。
• TestFlight（iOS）/ Closed 或 Open Testing（Android）。 行为与生产环境非常接近。收据采用生产环境格式。交易会进入 RevenueCat 的生产环境控制面板，而不是 Sandbox 视图。
• Production。 真实交易。请勿用于测试。

从能够解决问题的最低保真度渠道开始，然后逐步提高保真度。UI 和付费墙的迭代应使用快速渠道。“我的权益是否真的发生了变化？”这类问题应使用沙盒或内部测试。

测试商店：何时优先使用它，而不是沙盒

RevenueCat 的测试商店是一个合成商店提供方，可在控制面板中按项目配置。它会生成真实的 RevenueCat 后端记录（CustomerInfo 更新、权益变更、控制面板交易），但不会调用 App Store 或 Google Play。速度的代价是保真度。测试商店不会模拟“询问购买”审批流程、特定地区的定价、服务器端收据验证的具体行为、商店级别的审核或拒绝路径，也不会完整模拟订阅续订周期（测试商店会在压缩的时间线上续订最多五次）。

如果你想快速迭代 UI、编写结果可确定的集成测试，或运行 CI 检查，请使用测试商店。对于涉及商店端行为的测试，请改用 App Store 沙盒或 Google Play 内部测试。

设置。 在控制面板中，前往 Apps and providers → Test configuration 部分 → Test Store → Create / Enable。测试商店 API 密钥显示在 Project Settings → API keys 下，前缀为 test_。在调试构建中使用测试密钥配置 SDK，在发布构建中使用生产密钥（appl_… / goog_…）。平台文件中展示了各平台切换密钥的模式。

测试商店密钥绝不能随生产版本发布。请通过构建配置控制密钥，确保发布二进制文件不会通过测试商店路由。

沙盒交易会单独显示在控制面板中

RevenueCat 控制面板提供 Sandbox 和 Production 视图切换。沙盒购买只会显示在 Sandbox 视图中。如果测试交易没有显示在那里，说明 SDK 未上报该交易（请检查 API 密钥、configure 调用和网络），或者此次购买使用的 StoreKit 配置文件不会将交易发送到 RevenueCat 后端。

沙盒中的加速续订

沙盒中的订阅续订会使用加速测试时钟。这样你就可以在几分钟内测试续订逻辑，而不必等待几周。

• iOS 沙盒续订周期（根据 Apple 文档）：每日 → 每 3 分钟、每周 → 每 3 分钟、每月 → 每 5 分钟、每 2 个月 → 每 10 分钟、每 3 个月 → 每 15 分钟、每 6 个月 → 每 30 分钟、每年 → 每小时。订阅自动续订最多 6 次，随后到期。
• Android 沙盒续订周期记录在 Google Play Console → Subscriptions testing 中。许可测试者的订阅使用相同的加速时钟续订。

首次购买流程请使用全新的测试用户

购买历史会关联到测试账号（沙盒 Apple ID 或许可测试者 Gmail），并会持续保留。使用已享受过首次购买优惠、入门优惠或免费试用的账号测试相关逻辑，会产生误导性结果。请创建新的沙盒测试者，以便干净地测试首次购买场景。

以控制面板为准，而非设备

设备上显示购买成功，并不代表 RevenueCat 已记录这笔交易。请务必确认：

1. 交易显示在 RevenueCat 控制面板的 Sandbox 视图中。
2. 交易归属于预期的 appUserID。
3. 预期权益现已在该用户上激活。

如果设备显示成功，但控制面板中没有任何记录，问题出在配置路径，而非商店。

3. 实现

阅读与检测结果相符的平台文件：

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

4. 验证

测试环境设置完成后，应满足以下条件：

1. 测试用户成功完成端到端的测试购买。
2. 交易显示在 RevenueCat 控制面板的 Sandbox 视图中，并关联到你登录时使用的 appUserID。
3. 购买完成后，预期权益在 customerInfo 上处于激活状态。
4. 在全新安装的应用中恢复购买后，权益会恢复给同一个测试用户。

如果上述四个步骤中有任何一步失败，说明环境尚未就绪。revenuecat-troubleshoot 技能涵盖了常见根本原因。