rc-payment-recovery

付款恢复

续订失败后，Google Play 会让订阅依次进入两种状态：宽限期（Google 重试扣款期间，用户仍可访问）和账户保留期（撤销访问权限，直到用户修复付款方式）。使用 RevenueCat 时，这两种状态都会自动显示在 CustomerInfo 中，Google 的应用内消息也会默认显示。

阶段 1：了解

续订失败时会发生三件事：

状态	访问权限	RevenueCat 如何呈现	用户看到的内容
宽限期	保留	entitlement.isActive == true 且 billingIssueDetectedAt != null	默认显示 Google 应用内提示条
账户保留期	撤销	entitlement.isActive == false 且 billingIssueDetectedAt != null	默认显示 Google 应用内提示条
已恢复	保留	billingIssueDetectedAt == null	无

SDK 中有两个重要信号：

• 从 Google 报告付款问题开始，直到用户解决问题，EntitlementInfo.billingIssueDetectedAt 都为非空。
• EntitlementInfo.isActive 用于判断用户是否仍有访问权限。

在后端，每次状态转换都会触发一次 BILLING_ISSUE webhook。你无需解析 RTDN。

阶段 2：规划

编写应用代码之前，先确定你的实际需求。大多数应用什么都不需要做。

请思考：

1. 你想使用默认的 Google 应用内消息吗？如果是，无需操作。SDK 在连接 BillingClient 时会调用 showInAppMessagesIfNeeded。
2. 你想显示自己的横幅或对话框吗？如果是，请从 CustomerInfo 读取 billingIssueDetectedAt，并根据 isActive 分支处理。
3. 你想让消息仅在特定屏幕上显示吗？如果是，请停用自动调用，并自行调用 showInAppMessagesIfNeeded(activity)。
4. 你需要服务端标记（例如，用于发送付款恢复邮件）吗？如果是，请处理 BILLING_ISSUE webhook。无需编写应用代码。

如果你只想使用默认行为，请到此为止。

阶段 3：执行

默认设置（推荐）

保持应用内消息自动显示。此设置为默认值：

PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(true)
    .build()

手动触发

停用自动调用，并从你选择的 activity 显示消息：

PurchasesConfiguration.Builder(context, apiKey)
    .showInAppMessagesAutomatically(false)
    .build()

Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)

宽限期内显示自定义 UI

读取权益信息，并根据两个标志进行分支处理：

val entitlement = customerInfo.entitlements["pro_access"]
when {
    entitlement == null || !entitlement.isActive ->
        showSubscribeScreen()
    entitlement.billingIssueDetectedAt != null && entitlement.isActive ->
        showGracePeriodWarning()
    entitlement.billingIssueDetectedAt != null && !entitlement.isActive ->
        showAccountHoldScreen()
    else ->
        showPremiumContent()
}

引导用户修复付款方式

CustomerInfo.managementURL 指向 Google Play 订阅页面：

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

阶段 4：验证

测试每次状态转换：

• 使用一张会拒绝续订付款的 Google Play 测试卡，让订阅进入宽限期。
• 确认 entitlement.billingIssueDetectedAt 变为非空，且 isActive 仍为 true。
• 等待进入账户保留期，并确认 isActive 变为 false，而 billingIssueDetectedAt 仍为非空。
• 更新付款方式，并确认 billingIssueDetectedAt 恢复为 null。
• 在后端确认首次状态转换时会触发 BILLING_ISSUE webhook。

参考资料

• 完整章节