Android 订阅续费失败时用 RevenueCat…

在 Android 应用使用 RevenueCat 时，处理 Google Play 续费失败后的宽限期（grace period）与账户冻结（account hold）状态，并决定是否提示用户或触发 Google 应用内消息。

适用场景

解决思路

1. 理解续费失败后的三种状态：宽限期（保留访问权限，entitlement.isActive == true 且 billingIssueDetectedAt != null）、账户冻结（撤销访问权限，entitlement.isActive == false 且 billingIssueDetectedAt != null）、已恢复（保留访问权限，billingIssueDetectedAt == null）。
2. 在 SDK 中关注两个信号：EntitlementInfo.billingIssueDetectedAt 从 Google 报告账单问题起非空，直到用户解决；EntitlementInfo.isActive 表示用户是否仍有访问权限。
3. 后端会为每次状态转换触发一次 BILLING_ISSUE webhook，无需自行解码 RTDN。
4. 规划阶段先确认需求：若只需默认 Google 应用内消息，则无需编写任何应用代码，SDK 会在 BillingClient 连接时调用 showInAppMessagesIfNeeded。
5. 若需要自定义横幅或对话框，从 CustomerInfo 读取 billingIssueDetectedAt 并根据 isActive 分支处理。
6. 若需要将消息限制在特定页面，禁用自动调用并自行调用 showInAppMessagesIfNeeded(activity)。
7. 若需要服务端标记（例如发送挽回邮件），处理 BILLING_ISSUE webhook，无需应用代码。
8. 默认推荐做法：保持自动应用内消息开启，使用 PurchasesConfiguration.Builder(context, apiKey).showInAppMessagesAutomatically(true).build()。
9. 手动触发做法：禁用自动调用（showInAppMessagesAutomatically(false)），并在选定 Activity 中调用 Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)。
10. 宽限期自定义 UI：读取 entitlement 并根据两个标志分支——entitlement 为 null 或 !isActive 时显示订阅页；billingIssueDetectedAt != null 且 isActive 时显示宽限期警告；billingIssueDetectedAt != null 且 !isActive 时显示账户冻结页；否则显示高级内容。
11. 引导用户修复支付：使用 CustomerInfo.managementURL 指向 Google Play 订阅页面，通过 startActivity(Intent(Intent.ACTION_VIEW, url)) 打开。
12. 验证各状态转换：使用会拒绝续费的 Google Play 测试卡将订阅推入宽限期，确认 billingIssueDetectedAt 变为非空且 isActive 保持 true。
13. 等待进入账户冻结，确认 isActive 变为 false 且 billingIssueDetectedAt 仍非空。
14. 更新支付方式后，确认 billingIssueDetectedAt 恢复为 null。
15. 在后端确认首次转换时触发 BILLING_ISSUE webhook。

适用边界 · 注意事项

• 不使用 RevenueCat 或不在 Android 平台处理订阅续费失败时不适用。
• 如果只需要 Google 默认的应用内消息行为，无需编写任何应用代码，不要过度实现自定义逻辑。
• 不依赖 Google Play 订阅体系（如使用其他支付渠道）时不适用。