在 Android 用 RevenueCat…

当用户已有活跃的 Google Play 订阅、需要切换到不同 SKU（升级、降级、交叉升级或试用转正）时，用 RevenueCat 的 PurchaseParams 与 GoogleReplacementMode 完成计划变更。

适用场景

解决思路

1. 确认前置条件：用户恰好有一个要替换的活跃 Google Play 订阅；通过 Purchases.sharedInstance.awaitCustomerInfo() 或最近监听回调拿到新鲜的 CustomerInfo；从 offerings.current 解析出目标 Package；classpath 上有 RevenueCat SDK 带来的 Google Play Billing Library 7+。
2. 根据用户意图选择 GoogleReplacementMode：标准升级（月付转年付）用 WITH_TIME_PRORATION（立即切换，剩余时间折算抵扣）；升级但保留原账单日 用 CHARGE_PRORATED_PRICE（立即切换，现在按比例收费）；切换到或切出预付费计划用 CHARGE_FULL_PRICE（立即切换，现在收全款）；活跃免费试用期内升级用 CHARGE_PRORATED_PRICE（立即切换，现在按比例收费）；降级（年付转月付）用 DEFERRED（下次续订时生效）。
3. 不要对试用升级默认使用 WITHOUT_PRORATION：它会立即应用新计划但直到下次续订才收费，等于让用户免费获得未付费的高级权限；应改用 CHARGE_PRORATED_PRICE 当场收取升级费用。
4. 每次都要显式设置替换模式：若不设置，PurchaseParams 默认是 WITHOUT_PRORATION。
5. 注意 DEFERRED 只对降级有效，Google 会拒绝延迟升级。
6. 从 CustomerInfo 推导 currentProductId，不要硬编码 SKU（用户迁移计划后会失效）：取 customerInfo.activeSubscriptions.firstOrNull()?.substringBefore(":")，因为 activeSubscriptions 条目形如 "productId:basePlanId"，需去掉 base plan 后缀；若为空说明没有活跃订阅，改走 make-purchase 流程。
7. 从 offerings.current?.availablePackages 中按 identifier 找到目标 Package（如 "premium_annual_package"）。
8. 用 PurchaseParams.Builder(activity, newPackage).googleProductChangeInfo(GoogleProductChangeInfo(oldProductId = currentProductId, replacementMode = GoogleReplacementMode.WITH_TIME_PRORATION)).build() 构建参数，然后调用 Purchases.sharedInstance.awaitPurchase(params)，结果中的 result.customerInfo 反映新订阅。
9. 捕获 PurchasesTransactionException：若 !e.userCancelled 则展示 e.error.message。
10. oldProductId 只传订阅产品 ID；虽然传 "basic_monthly:monthly_plan" 时 SDK 会替你剥掉 ":monthly_plan"，但自己用 substringBefore(":") 切掉更清晰。
11. 执行后验证：customerInfo.activeSubscriptions 现在包含新的 productId:basePlanId；customerInfo.entitlements["pro"]?.isActive 在切换过程中保持 true，不要用 SKU 字符串来控制 UI。
12. DEFERRED 模式下，activeSubscriptions 在下次续订前仍报告旧产品；RevenueCat 在服务端跟踪待生效切换，并在 Google 发送续订 RTDN 后翻转权益。
13. 不要编写 linkedPurchaseToken 遍历代码：RevenueCat 会在服务端解析链路、把旧 token 标记为已替换，并把两个 token 归属到同一个 App User ID；客户端只读权益并信任它。
14. 避免常见错误：不要硬编码 oldProductId 常量；不要把 "productId:basePlanId" 直接作为 oldProductId；不要对试用升级用 WITHOUT_PRORATION；不要对升级用 DEFERRED；不要写后端代码跟踪 linkedPurchaseToken；不要读 SKU 来决定 UI 状态，应读 entitlements[...]?.isActive。

适用边界 · 注意事项

• 用户没有活跃订阅时（应改用 make-purchase 做全新购买）。
• 需要全新购买而非替换现有订阅时。