rc-purchase-flow

用途

rc-purchase-flow 用于在 Android 上实现 RevenueCat 购买流程。按照该技能的说明，Android 上的 RevenueCat 购买只需两行代码：SDK 负责处理计费参数、Play 购买界面、购买令牌往返、服务端验证与确认，开发者只需决定传入哪个 package，以及如何处理返回的权益（entitlements）。

主要能力

awaitPurchase() 的底层行为

一次 Purchases.sharedInstance.awaitPurchase(params) 调用在底层执行六个步骤，开发者无需自行编写：

根据 Package 构建带有正确 ProductDetailsParams 的 BillingFlowParams。
针对传入的 activity 调用 BillingClient.launchBillingFlow()。
挂起，直到 PurchasesUpdatedListener 返回结果。
若结果为 OK，将 Play 购买令牌提交到 RevenueCat 后端。
后端通过 purchases.subscriptionsv2.get 或 purchases.products.get 进行验证。
SDK 在 Google 规定的 3 天窗口内完成确认（订阅或非消耗型商品）或消耗（消耗型商品）。

该调用返回 PurchaseResult(storeTransaction, customerInfo)。可重试的失败会自动重试。

准备 Package

购买前需要从 offerings 中获取一个 Package。先获取 offerings，由 UI 选择一个，并持有 activity：

val offerings = Purchases.sharedInstance.awaitOfferings()
val pkg = offerings.current?.monthly ?: return

如果需要特定 offer 而非默认项，可解析一个 SubscriptionOption 并传给 PurchaseParams.Builder，而不是传 package：

val option = pkg.product.subscriptionOptions
    ?.firstOrNull { it.tags.contains("promo_50_off") }
    ?: pkg.product.defaultOption
    ?: return

对于欧盟的个性化定价，在 builder 上链式调用 .isPersonalizedPrice(true)，以便 Play 显示定制价格提示。

执行购买

构建参数、等待购买、读取 customerInfo 以控制访问，并处理两个预期错误分支：

try {
    val result = Purchases.sharedInstance.awaitPurchase(
        PurchaseParams.Builder(activity, pkg).build()
    )
    val customerInfo = result.customerInfo
    if (customerInfo.entitlements["pro"]?.isActive == true) {
        navigateToApp()
    }
} catch (e: PurchasesTransactionException) {
    when {
        e.userCancelled -> { /* backed out, do nothing */ }
        e.error.code == PurchasesErrorCode.ProductAlreadyPurchasedError ->
            showMessage("You already have this subscription")
        else -> showError(e.error.message)
    }
}

该代码块的规则：

PurchaseResult 是 @Poko。以 result.customerInfo 和 result.storeTransaction 访问字段，不要用 val (transaction, customerInfo) = result 解构。
customerInfo.entitlements["<id>"]?.isActive == true 是访问控制判断依据。不要检查 storeTransaction 来决定访问权限。
PurchasesTransactionException 是 awaitPurchase 抛出的唯一异常类型。捕获它，先判断 userCancelled，再判断 e.error.code。
用户取消不是需要展示的错误，直接吞掉。

如果偏好回调而非协程，purchaseWith(params, onError, onSuccess) 是等价的入口。

检查 StoreTransaction

result.storeTransaction 可用但通常不用。customerInfo 是权益的权威来源。如果需要事务级数据用于日志或自有后端，可参考以下字段：

orderId：String?，恢复购买时为 null。
purchaseToken：String，原始 Play 购买令牌。
productIds：List<String>，事务中的产品 ID。
purchaseTime：Long，epoch 毫秒。
type：ProductType，SUBS 或 INAPP。

重装或换机后恢复

恢复会运行 queryPurchasesAsync()，将找到的所有内容提交到 RevenueCat，并返回最新的 CustomerInfo。访问控制方式与购买后相同：

try {
    val customerInfo = Purchases.sharedInstance.awaitRestore()
    if (customerInfo.entitlements["pro"]?.isActive == true) {
        navigateToApp()
    } else {
        showMessage("No active purchases found")
    }
} catch (e: PurchasesException) {
    showError(e.error.message)
}

注意异常类型：awaitRestore() 抛出 PurchasesException，而不是 PurchasesTransactionException。由于不显示计费界面，没有 userCancelled 标志可检查。

异常类型一览

awaitPurchase(params)：抛出 PurchasesTransactionException，有 userCancelled。
awaitRestore()：抛出 PurchasesException，无 userCancelled。

使用方式

该技能以 RevenueCat 官方 AI 工具包中的技能形式提供，页面地址为 https://www.skills.sh/revenuecat/ai-toolkit/rc-purchase-flow。具体安装命令与集成步骤暂未提供。

适用场景

适用于在 Android 应用中接入 RevenueCat 购买流程的开发者，包括：处理订阅或非消耗型商品的购买、根据权益控制功能访问、处理用户取消与重复购买错误、在重装或换机后恢复购买，以及需要事务级数据用于日志或自有后端的场景。

限制

资料仅覆盖 Android 平台。价格、收费、具体平台支持范围等未在资料中说明，暂未提供。