revenuecat-paywall

revenuecat-paywall：展示 RevenueCat 付费墙

当用户想要展示在 RevenueCat 控制面板中构建和配置的付费墙，并使用原生 RevenueCatUI 组件时，请使用此技能。此技能不涵盖从头构建自定义付费墙。要实现此功能，请直接使用 revenuecat-purchase-flow 和 Purchases.getOfferings(…)。如果用户尚未在两者之间做出选择，请参阅 integrate-revenuecat 的第 5c 节。要创建、编辑、评估或审查控制面板中的付费墙，请使用 revenuecat-paywall-design。

前提条件：已运行 integrate-revenuecat。必须先成功调用 Purchases.configure(…)，才能加载付费墙。

1. 检测平台

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

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

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

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

• **付费墙需要在 RevenueCat 控制面板中关联了付费墙的 Offering。**SDK 通过 getOfferings() 获取 Offering。如果没有任何 Offering 配置付费墙，RevenueCatUI 会回退到默认付费墙布局，这不是生产环境所需的行为。
• **Offering 与权益。**用户通过 Offering 中的套餐购买产品。访问权限通过权益授予（通常为 "premium" 或 "pro"）。应根据权益而非 Offering 来限制高级功能。
• 三种展示模式：
  • （a）首次启动时向没有该权益的用户显示模态窗口，通常由“需要时展示”辅助方法驱动；此方法会检查权益，仅在用户缺少该权益时显示付费墙。
  • （b）受限的高级功能页面。用户点击高级功能后，付费墙会在页面加载前打开。
  • （c）用户点击 CTA 时有条件地展示，例如点击设置中的“升级”按钮。
• **RevenueCatUI 负责购买流程。**请勿在 RevenueCatUI 付费墙旁手动调用 Purchases.purchase(…)。付费墙会在内部调用它。请监听关闭或购买完成回调，以便在应用代码中做出响应。
• **大多数平台上的关闭按钮需选择启用。**以模态方式展示付费墙且用户需要退出方式时，请传入 displayCloseButton = true（iOS / Flutter / RN）或 setShouldDisplayDismissButton(true)（Android / KMP）。如果付费墙显示在带有自身拖动条的工作表后方，或付费墙被包装在导航控制器中，则无需启用。
• **如果用户选择完全自定义的 UI，请勿使用此技能。**请调用 Purchases.getOfferings() 并自行渲染组件。RevenueCatUI 仅适用于由控制面板模板化的付费墙。

3. 实现

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

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

每个平台文件都包含完整信息：安装命令、展示付费墙的准确代码片段，以及需要监听的回调形式。

4. 验证

只有满足以下条件，才能声称集成已完成：

1. 项目能在目标平台上构建。
2. 应用能够启动，展示付费墙的代码路径能够运行，并且付费墙 UI 使用在控制面板中配置的模板渲染（而非默认备用布局）。
3. 点按一个套餐并完成沙盒购买后，付费墙会关闭，并触发购买完成回调（或者对于命令式 API，返回 PURCHASED 结果）。
4. 关闭付费墙且不进行购买后，会触发关闭／取消回调。

如果付费墙显示的是默认备用布局，而不是你的模板，说明该商品尚未在控制面板中关联付费墙。请在控制面板中修复，然后重试。