revenuecat-paywall

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

revenuecat-paywall: display a RevenueCat paywall

revenuecat-paywall：展示RevenueCat付费墙

Use this skill when the user wants to show a paywall that is built and configured in the RevenueCat dashboard, using the native RevenueCatUI components. This skill does not cover building a custom paywall from scratch. For that, use

revenuecat-purchase-flow

(when available) and

Purchases.getOfferings(…)

directly.

Prerequisite:

integrate-revenuecat

has already run.

Purchases.configure(…)

must succeed before a paywall can load.

当用户希望使用原生RevenueCatUI组件展示在RevenueCat仪表盘中构建并配置好的付费墙时，可使用本技能。本技能不涵盖从零开始构建自定义付费墙的内容。如需构建自定义付费墙，请直接使用

revenuecat-purchase-flow

（若可用）和

Purchases.getOfferings(…)

。

前置条件：已执行

integrate-revenuecat

。付费墙加载前，

Purchases.configure(…)

必须执行成功。

1. Detect the platform

1. 检测平台

Inspect the working directory and pick the first match, from top to bottom:

React Native:
```
package.json
```
has a
```
react-native-purchases
```
entry, or
```
react-native
```
as a dependency.
```
react-native-purchases-ui
```
is the paywall package. Read
```
platforms/react-native.md
```
. If
```
expo
```
is also a dependency, note it as an Expo project.
Flutter:
```
pubspec.yaml
```
exists at the project root. The paywall package is
```
purchases_ui_flutter
```
. Read
```
platforms/flutter.md
```
.
Kotlin Multiplatform:
```
build.gradle.kts
```
contains a
```
kotlin { … }
```
multiplatform source sets block, or depends on
```
com.revenuecat.purchases:purchases-kmp*
```
. The paywall module is
```
purchases-kmp-ui
```
. Read
```
platforms/kmp.md
```
.

Android (native):

build.gradle(.kts)

applies

com.android.application

(and is not KMP). The paywall dependency is

com.revenuecat.purchases:purchases-ui

. Read

platforms/android.md

iOS (native):

Package.swift

*.xcodeproj

*.xcworkspace

, or

Podfile

at the project root. The paywall product is

RevenueCatUI

. Read

platforms/ios.md

If several match (e.g. an

ios/

folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.

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

React Native：
```
package.json
```
中包含
```
react-native-purchases
```
条目，或依赖
```
react-native
```
。付费墙包为
```
react-native-purchases-ui
```
。请阅读
```
platforms/react-native.md
```
。若同时依赖
```
expo
```
，则标记为Expo项目。
Flutter：项目根目录存在
```
pubspec.yaml
```
。付费墙包为
```
purchases_ui_flutter
```
。请阅读
```
platforms/flutter.md
```
。

Kotlin Multiplatform：

build.gradle.kts

包含

kotlin { … }

多平台源码集块，或依赖

com.revenuecat.purchases:purchases-kmp*

。付费墙模块为

purchases-kmp-ui

。请阅读

platforms/kmp.md

。

Android（原生）：

build.gradle(.kts)

应用了

com.android.application

（且非KMP项目）。付费墙依赖为

com.revenuecat.purchases:purchases-ui

。请阅读

platforms/android.md

。

iOS（原生）：项目根目录存在
```
Package.swift
```
、
```
*.xcodeproj
```
、
```
*.xcworkspace
```
或
```
Podfile
```
。付费墙产品为
```
RevenueCatUI
```
。请阅读
```
platforms/ios.md
```
。

若存在多个匹配项（例如Flutter项目内包含

ios/

文件夹），请选择最外层的项目，即拥有构建权限的项目。若仍存在歧义，请询问用户希望配置哪个平台。

2. Shared concepts (all platforms)

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

Paywalls require an Offering with a paywall attached in the RevenueCat dashboard. The SDK pulls offerings via
```
getOfferings()
```
. If no offering has a paywall configured, RevenueCatUI falls back to a default paywall layout, which is not what you want in production.
Offering vs. entitlement. Users purchase a product through a package in an offering. Access is granted via an entitlement (typically
```
"premium"
```
or
```
"pro"
```
). Gate premium features on the entitlement, not on the offering.
Three presentation patterns:
- (a) First launch modal for users without the entitlement, typically driven by a "present if needed" helper that checks the entitlement and only shows the paywall when missing.
- (b) Gated premium screen. The user taps a premium feature and the paywall opens before the screen loads.
- (c) Conditional present on a CTA tap, such as an "Upgrade" button in settings.
RevenueCatUI owns the purchase flow. Do not call
```
Purchases.purchase(…)
```
manually alongside a RevenueCatUI paywall. The paywall calls it internally. Listen for the dismiss or purchase completed callback to react in app code.
Close button is opt in on most platforms. Pass
```
displayCloseButton = true
```
(iOS / Flutter / RN) or
```
setShouldDisplayDismissButton(true)
```
(Android / KMP) when the paywall is presented modally and the user needs a way out. Skip it when presenting behind a sheet with its own grabber, or when wrapping the paywall in a navigation controller.
If the app needs a fully custom UI, do not use this skill. Call
```
Purchases.getOfferings()
```
and render your own components. RevenueCatUI is only for dashboard templated paywalls.

付费墙需要在RevenueCat仪表盘中关联一个Offering。 SDK通过
```
getOfferings()
```
拉取offerings。若没有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. Implementation

3. 实现步骤

Read the platform file that matches detection:

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

Each platform file is self contained: install command, exact snippet to present the paywall, and the callback shape you listen to.

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

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

每个平台文件均包含完整内容：安装命令、呈现付费墙的精确代码片段，以及需监听的回调格式。

4. Verify

4. 验证

Do not claim the integration is complete until:

The project builds on the target platform.
The app launches, the code path that presents the paywall runs, and the paywall UI renders with the template configured in the dashboard (not the default fallback layout).
Tapping a package and completing a sandbox purchase dismisses the paywall and fires the purchase completed callback (or, for imperative APIs, resolves with a
```
PURCHASED
```
result).
Closing the paywall without purchasing fires the dismiss / cancelled callback.

If the paywall shows the default fallback layout instead of your template, the offering does not have a paywall attached in the dashboard. Fix this in the dashboard, then retry.

在满足以下条件前，请勿声称集成完成：

项目可在目标平台构建成功。
应用启动后，触发呈现付费墙的代码路径可正常运行，且付费墙UI渲染出仪表盘中配置的模板（而非默认回退布局）。
点击套餐并完成沙盒购买后，付费墙关闭并触发购买完成回调（对于命令式API，则返回
```
PURCHASED
```
结果）。
未购买就关闭付费墙时，触发关闭/取消回调。

若付费墙显示默认回退布局而非自定义模板，说明Offering未在仪表盘中关联付费墙。请在仪表盘中修复该问题后重试。