revenuecat-migrate

revenuecat-migrate：迁移到 RevenueCat 或升级 SDK

当用户希望在已经上线应用内购买的应用中接入 RevenueCat，或跨主版本升级 RevenueCat SDK 时，使用此技能。

这两条路径共享一些概念，但风险各不相同。修改代码前，先确定适用哪条路径。

1. 检测平台

检查工作目录，并从上到下选择第一个匹配项：

1. React Native：package.json 中包含 react-native-purchases 条目，或将 react-native 作为依赖 → 阅读 platforms/react-native.md。如果 expo 也是依赖项，请注明这是一个 Expo 项目。
2. Flutter：项目根目录存在 pubspec.yaml → 阅读 platforms/flutter.md。
3. Kotlin Multiplatform：build.gradle.kts 包含 kotlin { … } 多平台源集代码块，或依赖 com.revenuecat.purchases:purchases-kmp* → 阅读 platforms/kmp.md。
4. Android（原生）：build.gradle(.kts) 应用了 com.android.application（且不是 KMP）→ 阅读 platforms/android.md。
5. iOS（原生）：项目根目录存在 Package.swift、*.xcodeproj、*.xcworkspace 或 Podfile → 阅读 platforms/ios.md。

如果有多个匹配项（例如 Flutter 项目中包含 ios/ 文件夹），请选择最外层、负责构建的项目。如果仍无法确定，请询问用户要配置哪个平台。

2. 确定迁移路径

询问用户（或根据代码库推断）：

• 路径 A：接入。 应用已经通过 StoreKit 或 Google Play Billing 直接实现了可正常使用的应用内购买。现在要在此基础上接入 RevenueCat。
• 路径 B：版本升级。 应用已经使用 RevenueCat，用户希望从一个主版本升级到下一个主版本（例如从 v4 升级到 v5、从 v7 升级到 v8）。

两条路径也可能同时进行（例如今天在最新主版本上接入 RC）。先执行路径 A，再根据需要执行路径 B。

3. 共享概念

观察者模式（路径 A）

观察者模式是接入 RevenueCat 而无需重写购买代码的关键方式。SDK 会观察现有 StoreKit / Billing 代码处理的交易，将其发送到 RevenueCat 后端进行验证，并更新订阅者状态，但不会发起或完成交易。现有购买界面、收据验证和交易完成逻辑都会保留。

在配置时设置此项：

• iOS：在 Configuration.Builder 上同时设置 purchasesAreCompletedBy: .myApp 和 storeKitVersion: .storeKit1（或 .storeKit2）。它们是两个独立参数，不是单个关联值。
• Android：在 PurchasesConfiguration.Builder 上设置 purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)。
• Flutter：将 const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2) 传递给 PurchasesConfiguration。
• React Native：在配置调用中传入 purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }。

默认由 RevenueCat 完成（REVENUECAT / .revenueCat），即 SDK 负责完整流程。

观察者模式稳定运行后，你可以选择稍后切换到完整 RevenueCat 模式：移除自有购买逻辑，并删除 purchasesAreCompletedBy 覆盖设置。

不要重复处理交易

当 purchasesAreCompletedBy 设置为 myApp 时，RevenueCat 不会在 iOS 上完成交易，也不会在 Android 上确认交易。你现有的代码必须继续执行这些操作。如果移除 myApp 标记，却保留旧的交易完成代码，交易就会被确认两次，订阅者状态也可能出现不一致。

完成 / 确认操作必须且只能由一方负责。选择一方，并移除另一方的处理逻辑。

用户连续性（路径 A）

如果应用已有自己的身份验证系统，请在配置 RevenueCat 后调用一次 Purchases.logIn(existingAppUserID)。这样在导入购买记录时，会将之前的购买历史关联到正确的 RevenueCat 用户。若不执行此步骤，现有购买记录会记在匿名 RC 用户名下，之后无法与应用的实际用户记录匹配。

只有当应用没有已登录用户的概念时，才跳过此步骤。

升级版本会改变必填字段（路径 B）

升级主版本会改变配置结构、移除已弃用的 API，并调整默认行为；这些变化会随每个版本而异。本技能不会重复列出各版本的差异。请查阅 SDK 仓库中的权威资料：

• 更新日志：在 GitHub 上查阅相关 SDK 仓库中的更新日志。从你安装的版本开始，逐条查看到目标版本。
• 迁移指南：在 SDK 仓库中搜索匹配 *MIGRATION*.md 的文件，或查找 migrations/ 目录。主版本升级通常会附带专门的指南。该仓库 GitHub Releases 页面上主版本的发行说明通常会提供相关链接。
• 发行说明：该仓库 GitHub Releases 页面上各主版本的发行说明会概述破坏性变更。

以 SDK 仓库的文档为准。此处编写的任何特定版本差异都可能过时。platforms/ 下与你的目标平台对应的文件会列出需要查阅的确切仓库。

先制定计划，再进行迁移

在每个平台上都按以下顺序操作：

1. 在一个分支中将 SDK 升级到新的主版本。
2. 参考更新日志中的弃用和移除内容，修复编译错误。
3. 在首次启动时查看 SDK 日志，修复运行时行为。
4. 在合并前运行现有测试套件，并手动测试沙盒场景。

4. 实现

根据检测结果，阅读对应的平台文件：

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

每个平台文件都涵盖该平台的两种迁移路径。

5. 验证

满足以下条件后，才能宣布迁移完成：

1. 应用在新 SDK 版本上成功构建，且你关注的已弃用 API 不再产生警告。
2. 沙盒购买成功，且交易显示在 RevenueCat 控制面板的 Sandbox 视图中，appUserID 符合预期。
3. 迁移前已有订阅的用户打开应用后，其权益状态正确。对于路径 A，这可以证明观察者模式的数据导入正常；对于路径 B，这可以证明版本升级没有丢失状态。
4. 发布前已移除调试日志级别覆盖设置。