rc-subscription-states

用途

rc-subscription-states 是一个面向 Android 的 RevenueCat 技能，用于在应用中根据 RevenueCat 订阅状态来门控功能访问，并驱动与订阅状态相关的界面。它解决的核心问题是：判断用户当前是否有权访问某项功能，以及如何向用户解释其订阅状态（如支付问题、已取消但仍在有效期内、暂停等）。

主要能力

技能围绕 CustomerInfo 与 EntitlementInfo 两个对象展开，提供以下能力：

读取 CustomerInfo，并通过 entitlement.isActive 判断用户当前是否有访问权限。
使用其他字段提供上下文：willRenew（是否会在周期末续订）、expirationDate（付费访问何时结束）、periodType（试用、介绍期、预付或正常周期）、billingIssueDetectedAt（是否存在支付问题）、unsubscribeDetectedAt（是否已取消但仍有剩余时间）、store（由哪个商店发放权益）。
对比 Google Play 的七种订阅状态（ACTIVE、IN_GRACE_PERIOD、CANCELED、ON_HOLD、PAUSED、EXPIRED、PENDING）与 RevenueCat 的布尔值方案，说明 RevenueCat 在后端从 Google SubscriptionPurchaseV2 资源计算状态，并暴露为 EntitlementInfo.isActive 一个字段。
提供决策规则：以 isActive == true 作为功能门控的唯一依据；用 billingIssueDetectedAt != null 显示修复支付提示；用 unsubscribeDetectedAt != null 配合 expirationDate 显示续订提醒；用 !willRenew（且无支付问题、无显式取消时间戳）显示不续订通知。
提供状态感知界面的实现示例，根据不同的信号展示对应消息。
支持多设备用户识别：通过 awaitLogIn 合并匿名购买与已识别用户，logOut 开始新的匿名会话。
通过 updatedCustomerInfoListener 监听 CustomerInfo 更新，使界面能响应购买、恢复和后台刷新，无需手动轮询。

使用方式

技能按四个阶段组织：

发现：在写代码前确认要检查的内容，包括哪个权益标识符门控功能、是否需要纯访问布尔值还是需要解释原因、需要缓存值还是新获取的值、是启动时刷新一次还是响应实时变化。
规划：理解 Google 七种状态与 RevenueCat 布尔值的对应关系，明确需要读取哪些字段以及何时读取，并应用决策规则。
执行：读取 CustomerInfo 并检查访问权限，例如：

val customerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val hasAccess = customerInfo.entitlements["pro_access"]?.isActive == true

awaitCustomerInfo() 会立即返回磁盘缓存，然后在后台从网络刷新，因此权益检查即使在离线时也保持快速。当需要强制获取最新值时（例如服务器端发放了促销），可使用：

val fresh = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

驱动状态感知界面的示例：

fun updateUI(entitlement: EntitlementInfo?) {
    if (entitlement == null || !entitlement.isActive) {
        showSubscribeScreen(); return
    }
    showPremiumContent()
    when {
        entitlement.billingIssueDetectedAt != null -> showBillingIssueWarning()
        entitlement.unsubscribeDetectedAt != null ->
            entitlement.expirationDate?.let { showExpiryNotice(it) }
        !entitlement.willRenew -> showNonRenewingNotice()
    }
}

多设备用户识别示例：

val result = Purchases.sharedInstance.awaitLogIn("your_user_id")
val customerInfo = result.customerInfo
val createdNewUser = result.created

验证：注册监听器以响应更新：

Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { info ->
        val active = info.entitlements["pro_access"]?.isActive == true
        updateAccessGate(active)
    }

注意：当 SDK 启动时命中缓存且没有变化，监听器不会触发，因此除了设置监听器外，还应在启动时调用 awaitCustomerInfo()。

适用场景

在 Android 应用中根据订阅状态门控高级功能。
需要向用户展示支付问题、取消后剩余有效期、不续订等状态提示。
需要处理多设备登录与匿名购买合并。
需要响应购买、恢复、后台刷新等实时订阅变化。
需要在离线启动时仍能基于缓存进行访问门控。

限制

技能面向 Android 平台。
资料未提供其他平台的支持情况。
资料未提供具体的收费、价格或平台要求信息。
资料未提供安装命令或依赖配置说明。
资料未提供性能指标或效果承诺。

技能介绍

用途

主要能力

使用方式

适用场景

限制