integrate-revenuecat

integrate-revenuecat：端到端 RevenueCat 集成

当用户想首次将 RevenueCat 添加到项目，或使用公开 API 密钥重新配置 SDK 时，使用此技能。此技能涵盖两部分：

1. 控制面板端 — 通过 RevenueCat MCP 服务或 rc CLI 设置项目、注册应用并获取公开 API 密钥。
2. 应用端 — 安装 Purchases SDK，在应用入口调用 Purchases.configure(…)，并在日志中确认配置横幅。

配置好 SDK 后，在编写任何付费墙代码之前，先确定如何构建付费墙（第 5c 节）。

按顺序引导用户完成。大多数集成都需要这两部分，即使用户说“只安装 SDK”也不例外——SDK 需要从控制面板获取 API 密钥。

如果项目和应用已存在，且用户只想在代码中接入 SDK，请跳到下面的第 3 节。 如果用户想从头开始创建全新的 RevenueCat 项目（应用 + 产品 + 权益 + 产品包），请改用 create-revenuecat-project 技能，然后回到这里安装 SDK。

参数

作为斜杠命令调用时，可通过 $ARGUMENTS 获取：

• platform（可选）：ios、android、kmp、flutter、react-native 之一。如果未提供，请运行第 3a 节中的检测算法。
• app_identifier（可选）：Bundle ID（iOS）或包名（Android）。如果未提供，请从项目文件（Info.plist、AndroidManifest.xml、app.json、pubspec.yaml）中读取。
• project_name（可选）：要使用的 RevenueCat 项目名称。如果未提供，请列出项目（通过 MCP 或 rc projects list）并询问用户。

1. 了解当前情况

操作控制面板之前，先收集相关信息：

• 目标平台：iOS / Apple App Store、Android / Google Play，或两者。先检查工作目录再提问——对于大多数项目，第 3 节中的检测算法可以直接判断。
• 技术栈：原生 iOS（Swift）、原生 Android（Kotlin / Java）、React Native、Flutter、Kotlin Multiplatform。SDK 列表：https://www.revenuecat.com/docs/getting-started/installation.md。
• 应用标识符：Bundle ID（iOS）、包名（Android）。从 Info.plist / AndroidManifest.xml / app.json / pubspec.yaml 中读取，不要询问用户。

2. 控制面板端

使用用户可用的方式：RevenueCat MCP 服务或 rc CLI（CLI 的发现方式和使用约定请参阅 revenuecat-cli 技能）。这两种方式都支持完成这些步骤中的相同操作，每个步骤都会列出对应的 MCP 工具和 rc 命令。

2a. 获取或创建项目

• 列出可访问的项目：使用 list-projects（MCP）或 rc projects list。如果有多个项目，询问用户哪个项目对应此应用，或提出创建新项目（create-project / rc projects create）。
• 如果没有项目，请转交给 create-revenuecat-project 技能，然后回到这里继续。
• 保存 project_id，供后续步骤使用。

2b. 获取或创建应用

• 检查项目中已配置的应用（list-apps / rc apps list）。始终会有一个 test_store 应用；只有用户完成商店端设置后，才会有 app_store 和 play_store 应用。
• 询问用户是否已在 App Store Connect（iOS）或 Google Play Console（Android）中设置应用。请告知用户，商店端设置可以稍后完成——开始集成时，只需有 test_store 应用即可。
• 如果用户确认已完成商店端设置，请调用 create-app（或 rc apps create）：
  • iOS：type: "app_store"，bundle_id 使用第 1 节中的值。
  • Android：type: "play_store"，package_name 使用第 1 节中的值。
  • name 根据标识符确定，或询问用户。

2c. 获取公开 API 密钥

• 列出相关应用 ID 的公开密钥：list-public-api-keys（MCP）或 rc apps keys <app-id>：
  • 如果商店端应用已存在，则使用 app_store / play_store。
  • 否则使用 test_store 应用。
• 返回的密钥是公开密钥，可以安全地嵌入客户端应用代码。iOS 密钥以 appl_… 为前缀，Android 密钥以 goog_… 为前缀，Amazon 密钥以 amzn_… 为前缀。

切勿在客户端代码中使用私有 API 密钥。 私有密钥仅用于服务端。

3. 应用端 — 安装并配置 SDK

3a. 检测平台

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

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/ 文件夹），选择最外层的项目，也就是拥有构建配置的项目。如果仍无法确定，请询问用户要配置哪个平台。

3b. 通用概念（所有平台）

• 使用公开 SDK 密钥，而非私有密钥。 RevenueCat 会为每个商店／平台单独签发公开 SDK 密钥。iOS 应用使用 appl_… 密钥，Android 应用使用 goog_… 密钥（Amazon 使用 amzn_…）。服务端私有密钥绝不能出现在客户端应用中。
• 每次应用启动时配置一次。 尽早调用一次 Purchases.configure(…)（应用入口点）。之后的调用会被忽略或触发警告。
• 用户默认匿名。 如果不传入 appUserID，RevenueCat 会创建一个稳定的匿名 ID。仅当应用启动时已有经过身份验证的用户，才传入 appUserID；否则稍后调用 logIn(…)（参见 revenuecat-identify-user 技能）。
• 集成期间启用调试日志。 各平台文件中都有说明。发布构建时请关闭调试日志。
• 不要将密钥提交到源代码管理中。 用户询问密钥管理时，建议使用 .env（RN）、xcconfig（iOS）、local.properties / gradle.properties（Android）或 dart-define（Flutter）。

3c. 实现

阅读与检测结果匹配的平台文件：

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

每个平台文件都包含完整说明：安装命令、准确的 configure 代码片段，以及在应用入口点中的放置位置。

4. 验证

在以下事项完成之前，不要声称配置已完成：

1. 项目能够构建（Xcode 构建、./gradlew assembleDebug、flutter run、npx react-native run-ios 或对应的 KMP 命令）。
2. 应用能够启动，并且 RevenueCat SDK 在控制台／logcat／Metro 输出中记录配置横幅（各平台文件会说明预期的日志行）。
3. 首次 SDK 网络调用时没有出现身份验证错误。如果 API 密钥错误，应用获取套餐时会立即出现身份验证错误日志。

如果用户只要求“安装”，而没有运行应用，请告知他们运行应用时需要在日志中查看哪些内容。

5. 后续步骤

5a. 产品、权益、套餐

检查项目中是否已设置产品、权益和套餐。如果尚未设置，可以提出通过 create-revenuecat-project 技能提供帮助。

5b. 商店端设置

iOS（App Store Connect）

1. 应用内购买密钥（推荐用于 StoreKit 2） — App Store Connect → Users and Access → Integrations → In-App Purchase。生成密钥并下载 .p8 文件。记下 Key ID 和 Issuer ID。
2. 共享密钥（旧版 StoreKit 1） — App Store Connect → App → App Information → App-Specific Shared Secret。
3. 如果用户提供了这些信息，通过 create-app / update-app 在 RevenueCat 端注册。

Android（Google Play Console）

1. 服务账号凭据 — 在 Google Cloud Console 中创建服务账号。授予“Service Account User”角色。创建 JSON 密钥。在 Play Console 中，授予该服务账号访问权限，并赋予“View financial data”权限。
2. 实时开发者通知（RTDN） — 设置 Cloud Pub/Sub 主题。在 Play Console → Monetization setup 中进行配置。
3. 如果用户提供了这些信息，通过 create-app / update-app 注册。

5c. 选择付费墙的构建方式

应用仍然需要付费墙，有两种构建方式。这是产品决策，而非实现细节，因此要在编写任何付费墙代码之前确定。

• RevenueCat Paywall（推荐的默认选项）。 由 RevenueCat 托管，并由 RevenueCatUI 渲染。由你自行创建：加载 revenuecat-paywall-design 技能并遵循其创建工作流（通过 MCP 使用 create-paywall-ai，或通过 CLI 使用 rc paywalls generate；关联到当前 offering，并参考应用的代码库），然后使用 revenuecat-paywall 展示。用户无需在控制面板中设计任何内容，之后可以在付费墙构建器中进行调整。设计、文案和套餐可在不发布应用的情况下更改，并且可以通过 RevenueCat Experiments 对付费墙变体进行 A/B 测试。
• 在代码中构建自定义付费墙。 使用应用自身的 UI，通过 getOfferings() 获取套餐和价格，并由 revenuecat-purchase-flow 处理购买。拥有完全的视觉控制权，但每次设计变更都必须随应用版本发布，并且无法对付费墙设计进行 A/B 测试。价格和 offering 测试仍然有效，因为套餐来自 offering。

选择方案：

1. 用户已经说明想用哪种方案。 按用户选择执行。
2. 应用尚无付费墙页面。 推荐使用 RevenueCat Paywall。
3. 应用已有付费墙或订阅页面（列出方案或价格的页面、订阅或升级按钮、硬编码的价格或产品 ID）。用户很可能希望将该页面接入 offerings。建议保留现有页面，并说明可以用 RevenueCat Paywall 替换。

如果可以询问用户，就问一个问题，列出两种方案，先列推荐方案，并分别用一句话说明取舍。如果无法询问（例如，在非交互模式下运行），不要停下：采用上述推荐方案，并在总结中说明你选择的方案以及如何切换到另一种方案。

默认情况下，不要仅仅因为这样可以让工作保留在代码中，就手写付费墙页面。新的 RevenueCat Paywall 是尚未发布的草稿：告知用户在付费墙构建器中检查该草稿，只有在用户要求时才发布，因为在付费墙发布并关联到 offering 之前，应用会渲染默认后备布局。

5d. 后续技能

integrate-revenuecat 之后的常见后续步骤：

• revenuecat-paywall-design — 创建或编辑控制面板中的付费墙。
• revenuecat-paywall — 展示通过控制面板配置的付费墙。
• revenuecat-purchase-flow — 为自定义付费墙实现购买和恢复。
• revenuecat-entitlements-gate — 通过有效权益限制功能访问。
• revenuecat-identify-user — 将 logIn / logOut 接入应用的身份验证系统。
• revenuecat-testing-setup — 设置沙盒测试渠道。
• revenuecat-troubleshoot — 排查 offerings / 产品 / 权益问题。