从原生内购迁移到 RevenueCat 或升级…

当应用已有 StoreKit/Google Play Billing 内购想接入 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 { … } 多平台 source sets 块，或依赖 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. 确定迁移路径：询问用户或从代码库推断——Path A 接入：应用已有直接基于 StoreKit 或 Google Play Billing 的可用内购，正在其上叠加 RevenueCat；Path B 版本升级：应用已用 RevenueCat，要从一个大版本升到下一个（如 v4 到 v5、v7 到 v8）。两者可同时发生（如今天就在最新大版本上接入 RC），先跑 Path A，再按需跑 Path B。
3. Path A 使用 Observer 模式：让 SDK 观察现有 StoreKit/Billing 代码处理的交易，发送到 RevenueCat 后端校验并更新订阅者状态，但不发起也不完成交易；现有购买 UI、收据校验和交易完成逻辑保持不变。配置时设置：iOS 在 Configuration.Builder 上设 purchasesAreCompletedBy: .myApp 并配合 storeKitVersion: .storeKit1（或 .storeKit2），二者是独立参数而非单个关联值；Android 在 PurchasesConfiguration.Builder 上设 purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)；Flutter 向 PurchasesConfiguration 传 const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2)；React Native 在 configure 调用中传 purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }。默认是 RevenueCat 完成（REVENUECAT / .revenueCat），即 SDK 拥有完整流程。

适用边界 · 注意事项

• 应用尚无任何内购实现时，不适用接入路径（Path A），应直接按常规方式集成 RevenueCat。
• 应用没有已认证用户体系时，无需调用 Purchases.logIn(existingAppUserID)。
• 不确定目标平台或迁移路径时，不应直接改代码，应先询问用户确认。

经验正文