rc-cancellations-pauses-winback

用途

该技能面向在 Android 上使用 RevenueCat 的开发者，用于在应用内呈现订阅的取消、暂停与挽留（winback）状态。这些事件大多是「被动」的：应用观察它们，而不是主动发起它们。

主要能力

技能围绕 CustomerInfo 中的信号来识别状态：

已取消但仍可访问：entitlement.unsubscribeDetectedAt != null 且 isActive == true，可显示「ends on [expirationDate]」。
账单问题（宽限期或保留期）：entitlement.billingIssuesDetectedAt != null，表示支付失败、正在恢复中。
暂停：产品仍被拥有但 entitlement.isActive == false，恢复日期需要 REST API 查询。
正常续订：entitlement.willRenew == true。

后端挽留活动分群使用 CANCELLATION webhook 的 cancel_reason 字段（UNSUBSCRIBE、BILLING_ERROR、DEVELOPER_INITIATED、PRICE_INCREASE）。

使用方式

准备阶段：确认已通过 Purchases.sharedInstance.getCustomerInfo(...) 或监听器获取到 CustomerInfo，无需调用 BillingClient.queryPurchasesAsync 并设置 setIncludeSuspendedSubscriptions(true)，RevenueCat 从服务端订阅状态解析暂停状态。

规则：

managementURL 已是 Uri?，直接传给 Intent，不要调用 Uri.parse(url.toString())。
不要从 expirationDate 手动计算访问权限，应读取 isActive 和 willRenew。
暂停恢复日期不在 SDK 中，需在后端从 /v1/subscribers/{app_user_id} 获取。

执行阶段示例：

检测取消但仍有访问权限：

val entitlement = customerInfo.entitlements["pro_access"]
if (entitlement?.unsubscribeDetectedAt != null && entitlement.isActive) {
    entitlement.expirationDate?.let { expiry ->
        showCancellationBanner(expiry)
    }
}

unsubscribeDetectedAt 在 RevenueCat 收到 SUBSCRIPTION_CANCELED RTDN 时设置，isActive 在计费周期结束前保持 true。

检测暂停：

val entitlement = customerInfo.entitlements["pro_access"]
val hasAccess = entitlement?.isActive == true
// When paused, isActive == false. Pause resume date is not in the SDK.

打开订阅管理页：

customerInfo.managementURL?.let { url ->
    startActivity(Intent(Intent.ACTION_VIEW, url))
}

通过 REST 查询暂停恢复日期（从后端调用）：

curl -H "Authorization: Bearer $RC_SECRET_API_KEY" \
  https://api.revenuecat.com/v1/subscribers/$APP_USER_ID

暂停时 subscription 对象包含 paused_expiration_time_ms，可通过自有端点暴露给客户端。

到期前重新订阅：Google 的到期前重新订阅流程触发 SUBSCRIPTION_RESTARTED，RevenueCat 清除 unsubscribeDetectedAt 并设置 willRenew = true，无需额外代码，重新读取 customerInfo 即可。

到期后重新订阅：触发 RENEWAL webhook 而非 INITIAL_PURCHASE，后端处理程序需在两个事件上都授予权益访问。

验证方式

取消横幅显示：在 Play 商店取消，拉取最新 CustomerInfo，确认 unsubscribeDetectedAt != null 且 isActive == true。
管理深链打开：点击链接，确认打开对应产品的 Play 订阅页。
暂停被反映：在 Play 商店沙盒中暂停，确认 entitlement.isActive == false。
暂停恢复日期：调用 /v1/subscribers/{id}，确认存在 paused_expiration_time_ms。
挽留被接受：接受 Play 配置的挽留优惠，确认购买以正常订阅形式出现在 CustomerInfo 中。

适用场景与限制

适用于需要在 Android 应用中展示订阅取消、暂停、账单问题状态，并引导用户进入管理页或挽留流程的场景。

限制与注意事项：

延期与撤销通过后端调用 Google Play Developer API（purchases.subscriptionsv2.defer、purchases.subscriptionsv2.revoke）完成，RevenueCat 处理产生的 RTDN 并自动更新 CustomerInfo。
挽留活动无需 SDK 代码，在 Play Console 或 RevenueCat 后台配置。
RevenueCat 目前不发出专门的暂停 webhook，暂停状态在 Google Play RTDN 被处理后出现在 CustomerInfo 中。
暂停恢复日期不在 SDK 中，必须通过 REST API 获取。

技能介绍

用途

主要能力

使用方式

验证方式

适用场景与限制