capacitor-in-app-purchases

Capacitor 应用内购买

在 Capacitor 应用中设置应用内购买和订阅，涵盖商店配置、插件集成、购买流程、收据验证和测试。

前置条件

1. Capacitor 6、7 或 8 应用（Capawesome Purchases 需要 Capacitor 8+；RevenueCat 需要 Capacitor 8+）。
2. 已安装 Node.js 和 npm。
3. 对于 iOS：付费的 Apple Developer Program 会员资格、已安装 Xcode，并且已在 App Store Connect 中创建应用。
4. 对于 Android：拥有 Google Play Developer 账号、已安装 Android Studio，并且已在 Google Play Console 中创建应用。

Agent 行为

• 分步引导。 一次引导用户完成一个步骤。切勿一次提出多个无关问题。
• 先自动检测，再提问。 检查项目中的平台（android/、ios/）、package.json 依赖项和 Capacitor 版本。只有在无法检测到某项内容时才询问用户。
• 一次做一个决定。 如果某个步骤需要用户输入，只提出这一个问题，等待回答后再继续。
• 提供明确选项。 给出具体选择（例如：“你想使用哪个应用内购买插件？（1）Capawesome Purchases（2）RevenueCat”），而不是开放式问题。

MCP 服务

有两个托管的 MCP 服务提供当前文档，因此它们始终比此技能附带的指导更新：

• Capawesome MCP 服务 — Capawesome 插件、Capawesome CLI 和 Capawesome Cloud。
• Capacitor MCP 服务（非官方）— Capacitor 本身：CLI、capacitor.config 文件、原生 Android 和 iOS 项目，以及官方插件 API。

两者都提供 search_docs 和 get_doc_page，因此在调用之前，请根据主题选择对应的服务。

• 如果 MCP 工具可用，请在负责该主题的服务上调用 search_docs，并使用 get_doc_page 阅读匹配的页面，然后再应用下方的指导。如果两者内容不一致，请以文档为准。
• 如果 MCP 工具不可用，请提及一次可以使用下方的命令添加这些服务，然后继续使用此技能。切勿因此中断流程。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"

任何一个服务都不需要账号或令牌即可访问文档。完整设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp 和 capacitor-mcp 技能。

流程

步骤 1：分析项目

通过读取项目文件自动检测以下内容——不要询问用户可以推断出的信息：

1. 平台：检查哪些目录存在（android/、ios/）。这些就是需要配置的平台。
2. Capacitor 版本：从 package.json 中读取 @capacitor/core 版本。
3. 现有应用内购买插件：检查 package.json 中是否已有 @capawesome-team/capacitor-purchases、@revenuecat/purchases-capacitor 或其他应用内购买插件。如果已找到，请告知用户，并询问是继续使用现有插件还是切换插件。

步骤 2：在 App Store Connect 中配置产品（iOS）

如果不存在 ios/，则跳过。

阅读 references/app-store-connect-setup.md，并引导用户在 App Store Connect 中创建应用内购买产品和订阅。内容包括：

• 接受所需的开发者协议
• 验证商家配置（付费 App 协议、银行账户、税务表格）
• 创建应用内购买产品（消耗型、非消耗型、订阅）
• 设置订阅组
• 产品状态要求

第 3 步：在 Google Play Console 中配置产品（Android）

如果不存在 android/，请跳过。

阅读 references/google-play-console-setup.md，并指导用户在 Google Play Console 中创建应用内购买产品。内容包括：

• 完成合规和元数据要求
• 创建应用内产品和订阅
• 配置定价和税务设置
• 激活产品

第 4 步：选择购买插件

询问用户要使用哪个插件：

1. Capawesome Purchases（@capawesome-team/capacitor-purchases）— 轻量级，不依赖第三方后端。需要 Capawesome Insiders 许可证。服务器端收据验证由开发者负责。
2. RevenueCat（@revenuecat/purchases-capacitor）— 完整的后端服务，提供服务器端收据验证、权益管理、分析和集成。需要 RevenueCat 账户。

默认建议：对于已有后端进行收据验证，或希望避免依赖第三方的应用，建议使用 Capawesome Purchases。对于希望开箱即用地获得托管收据验证和订阅分析的应用，建议使用 RevenueCat。

第 5 步：安装并配置插件

根据用户在第 4 步中的选择：

• Capawesome Purchases：阅读 references/capawesome-purchases-setup.md，并按照安装和平台配置步骤操作。
• RevenueCat：阅读 references/revenuecat-setup.md，并按照安装和平台配置步骤操作。

第 6 步：实现购买流程

根据用户选择的插件：

• Capawesome Purchases：阅读 references/capawesome-purchases-implementation.md，并将购买代码添加到项目中。
• RevenueCat：阅读 references/revenuecat-implementation.md，并将购买代码添加到项目中。

调整导入项和代码结构，以匹配用户所用的框架（Angular、React、Vue 等）。

实现内容包括：

1. 获取产品详情
2. 购买产品
3. 完成交易（Capawesome）或检查权益（RevenueCat）
4. 恢复购买
5. 处理应用启动时尚未完成的交易
6. 收据验证策略

第 7 步：配置可选功能

询问用户要启用哪些可选功能：

1. 订阅管理 — 显示订阅状态，处理续订和到期。
2. 入门优惠资格 — 检查用户是否符合入门定价条件（仅限 Capawesome Purchases）。
3. 服务器通知 — 为订阅生命周期事件设置 App Store Server Notifications 和/或 Google Play Real-time Developer Notifications。

对于每项选定的功能，阅读相应的实现参考文件并应用相关代码。

第 8 步：测试购买

阅读 references/testing.md，并指导用户在两个平台上测试应用内购买。内容包括：

• 使用测试账户进行 iOS Sandbox 测试
• 在 Xcode 中进行 iOS StoreKit Testing
• 使用 Google Play Console 内部测试轨道和许可测试账户进行 Android 测试
• 常见测试问题和调试技巧

第 9 步：同步并验证

npx cap sync

在每个平台上构建并运行，以验证购买流程端到端正常工作：

npx cap run android
npx cap run ios

错误处理

• 产品未显示：在 iOS 上，产品在 App Store Connect 中创建后，可能需要几个小时才能显示。确认产品状态为“Ready to Submit”或“Approved”。在 Android 上，确认产品状态为“Active”，且应用已上传到至少内部测试轨道。
• Android 上购买失败但没有提示：应用必须从 Google Play 安装（不能通过直接安装 APK 安装）。将应用上传到内部测试轨道，在 License Testing 下添加测试账号，然后从 Google Play 安装。
• iOS 沙盒购买循环或失败：确保设备已登录沙盒测试账号（iOS 14 及以上版本中，前往“设置” > “App Store” > “沙盒账户”）。测试时不要使用正式版 Apple ID。
• Android 上的 purchaseProduct() 返回错误：确认存在 google-services.json，且 Google Play Billing Library 版本兼容。检查 android/variables.gradle 中的 $googlePlayBillingVersion。
• 收据验证失败：在 iOS 上，通过 transaction.verificationResult 验证 JWS 令牌。在 Android 上，使用 Google Play Developer API 验证 transaction.token、transaction.originalJson 和 transaction.signature。
• 恢复购买未显示任何内容：在 iOS 上，syncTransactions() 会显示系统身份验证对话框，因此必须响应明确的用户操作调用（例如，用户点按“恢复购买”按钮）。在 Android 上，该操作会静默运行。
• 未调用 finishTransaction()：在某些平台上，未完成的交易会阻止后续购买。交付内容后务必调用 finishTransaction()。在每次应用启动时检查未完成的交易。
• 运行时未找到插件：确保安装后运行了 npx cap sync。对于 Capawesome Purchases，请确认已配置 Capawesome npm 注册表。
• Capacitor 版本不匹配：Capawesome Purchases 和 RevenueCat 均要求 Capacitor 8 或更高版本。检查 package.json 中的 @capacitor/core 版本。

相关技能

• capacitor-plugins — 了解 Capacitor 插件的一般安装和配置，包括 Capawesome Purchases 和 RevenueCat 插件。
• capawesome-cloud — 在配置应用内购买后发布应用到应用商店。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。