revenuecat-migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

revenuecat-migrate: migrate to RevenueCat or upgrade the SDK

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

Use this skill when the user wants to either adopt RevenueCat in an app that already ships in app purchases, or upgrade the RevenueCat SDK across a major version.

These two paths share some concepts but have different risks. Identify which one applies before touching code.

当用户希望在已实现应用内支付的应用中集成RevenueCat，或是对RevenueCat SDK进行跨大版本升级时，可使用本技能。

这两种路径有一些共通概念，但风险不同。在修改代码前需先确定适用哪种路径。

1. Detect the platform

1. 检测平台

Inspect the working directory and pick the first match, from top to bottom:

React Native:
```
package.json
```
has a
```
react-native-purchases
```
entry, or
```
react-native
```
as a dependency → read
```
platforms/react-native.md
```
. If
```
expo
```
is also a dependency, note it as an Expo project.
Flutter:
```
pubspec.yaml
```
exists at the project root → read
```
platforms/flutter.md
```
.
Kotlin Multiplatform:
```
build.gradle.kts
```
contains a
```
kotlin { … }
```
multiplatform source sets block, or depends on
```
com.revenuecat.purchases:purchases-kmp*
```
→ read
```
platforms/kmp.md
```
.

Android (native):

build.gradle(.kts)

applies

com.android.application

(and is not KMP) → read

platforms/android.md

iOS (native):

Package.swift

*.xcodeproj

*.xcworkspace

, or

Podfile

at the project root → read

platforms/ios.md

If several match (e.g. an

ios/

folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.

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

React Native：
```
package.json
```
中包含
```
react-native-purchases
```
条目，或依赖
```
react-native
```
→ 阅读
```
platforms/react-native.md
```
。若同时依赖
```
expo
```
，则标记为Expo项目。
Flutter：项目根目录存在
```
pubspec.yaml
```
→ 阅读
```
platforms/flutter.md
```
。

Kotlin Multiplatform：

build.gradle.kts

包含

kotlin { … }

多平台源码集块，或依赖

com.revenuecat.purchases:purchases-kmp*

→ 阅读

platforms/kmp.md

。

Android（原生）：
```
build.gradle(.kts)
```
应用
```
com.android.application
```
（且非KMP项目） → 阅读
```
platforms/android.md
```
。
iOS（原生）：项目根目录存在
```
Package.swift
```
、
```
*.xcodeproj
```
、
```
*.xcworkspace
```
或
```
Podfile
```
→ 阅读
```
platforms/ios.md
```
。

若多个条件匹配（例如Flutter项目内包含

ios/

文件夹），请选择最外层的项目，即拥有构建控制权的项目。若仍存在歧义，请询问用户要配置哪个平台。

2. Identify the migration path

2. 确定迁移路径

Ask the user (or infer from the codebase):

Path A: adoption. The app already has working in app purchases implemented directly against StoreKit or Google Play Billing. RevenueCat is being added on top.
Path B: version upgrade. The app already uses RevenueCat, and the user wants to bump from one major version to the next (e.g. v4 to v5, v7 to v8).

Both paths can happen at once (e.g. adopt RC today on the latest major version). Run Path A first, then Path B if needed.

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

路径A：集成。应用已通过原生StoreKit或Google Play Billing实现可用的应用内支付，现需在其基础上添加RevenueCat。
路径B：版本升级。应用已使用RevenueCat，用户希望从一个大版本升级至下一个版本（例如从v4升级到v5、v7升级到v8）。

两种路径可同时进行（例如直接集成最新大版本的RC）。先执行路径A，若需要再执行路径B。

3. Shared concepts

3. 通用概念

Observer mode (Path A)

观察者模式（路径A）

Observer mode is the key lever for adopting RevenueCat without rewriting purchase code. The SDK observes transactions that your existing StoreKit / Billing code processes, sends them to the RevenueCat backend for validation, and updates subscriber state, but does not initiate or finish the transactions. Your existing purchase UI, receipt validation, and transaction finishing stay in place.

Set this at configure time:

iOS: set
```
purchasesAreCompletedBy: .myApp
```
together with
```
storeKitVersion: .storeKit1
```
(or
```
.storeKit2
```
) on
```
Configuration.Builder
```
. They are separate parameters, not a single associated value.

Android:

purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)

PurchasesConfiguration.Builder

Flutter: pass

const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2)

PurchasesConfiguration

React Native: pass

purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }

in the configure call.

The default is RevenueCat completed (

REVENUECAT

.revenueCat

), where the SDK owns the full flow.

Once stable in observer mode, you can optionally cut over to full RevenueCat mode later by removing your own purchase plumbing and dropping the

purchasesAreCompletedBy

override.

观察者模式是无需重写支付代码即可集成RevenueCat的关键机制。SDK会监听现有StoreKit/Billing代码处理的交易，将其发送至RevenueCat后端进行验证，并更新订阅者状态，但不会发起或完成交易。您现有的支付UI、收据验证和交易完成逻辑将保持不变。

在配置时进行设置：

iOS：在

Configuration.Builder

上设置

purchasesAreCompletedBy: .myApp

以及

storeKitVersion: .storeKit1

（或

.storeKit2

）。它们是独立参数，而非单个关联值。

Android：在

PurchasesConfiguration.Builder

上调用

purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)

。

Flutter：将

const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2)

传入

PurchasesConfiguration

。

React Native：在configure调用中传入

purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }

。

默认值为RevenueCat完成（

REVENUECAT

.revenueCat

），即SDK掌控整个流程。

在观察者模式稳定运行后，您可选择后续切换至完整RevenueCat模式，只需移除自身的支付流程代码并取消

purchasesAreCompletedBy

的覆盖设置。

Do not double process transactions

请勿重复处理交易

When

purchasesAreCompletedBy

is set to

myApp

, RevenueCat does not finish transactions on iOS or acknowledge on Android. Your existing code must continue to do that. If you remove the

myApp

flag while leaving your old transaction finishing code in place, transactions get acknowledged twice and subscriber state can appear inconsistent.

Exactly one side must own finishing / acknowledging. Pick a side and remove the other.

当

purchasesAreCompletedBy

设置为

myApp

时，RevenueCat不会在iOS上完成交易，也不会在Android上确认交易。您的现有代码必须继续执行这些操作。如果您移除

myApp

标志但保留旧的交易完成代码，交易将被确认两次，导致订阅者状态出现不一致。

必须由且仅由一方负责完成/确认交易。选择其中一方并移除另一方的相关代码。

User continuity (Path A)

用户连续性（路径A）

If the app already has its own authentication system, call

Purchases.logIn(existingAppUserID)

once RevenueCat is configured. This attaches the prior purchase history to the right RevenueCat user on ingestion. Without this step, existing purchases get recorded against an anonymous RC user and cannot be matched to the app's actual user records later.

Only skip this if the app has no notion of authenticated users.

如果应用已有自己的认证系统，请在配置RevenueCat后调用

Purchases.logIn(existingAppUserID)

。这会将之前的购买历史关联到正确的RevenueCat用户。若跳过此步骤，现有购买记录将被关联到匿名RC用户，后续无法与应用的实际用户记录匹配。仅当应用无认证用户概念时可跳过此步骤。

Version bumps change required fields (Path B)

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

Major version upgrades change configuration shape, drop deprecated APIs, and shift default behavior in ways that move with each release. This skill does not duplicate the per-version diff. Read the canonical sources from the SDK repo:

CHANGELOG: in the relevant SDK repo on GitHub. Walk entries from your installed version up to the target.
Migration guides: search the SDK repo for files matching
```
*MIGRATION*.md
```
or a
```
migrations/
```
directory. Major bumps usually ship a dedicated guide there. The release notes for the major version on the repo's GitHub releases page typically link to it.
Release notes: each major version's release notes on the repo's GitHub releases page summarize the breaking changes.

Treat the SDK repo's docs as authoritative. Any version-specific diff written here would drift out of date. The platform file under

platforms/

for your target lists the exact repo to consult.

大版本升级会更改配置结构、移除已弃用的API，并改变默认行为，且每次版本更新的变化各不相同。本技能不会重复每个版本的差异内容，请查阅SDK仓库中的权威资料：

CHANGELOG：相关SDK在GitHub上的仓库中。从您当前安装的版本开始，逐一查看更新条目直至目标版本。
迁移指南：在SDK仓库中搜索匹配
```
*MIGRATION*.md
```
的文件或
```
migrations/
```
目录。大版本升级通常会附带专门的迁移指南。该大版本在仓库GitHub发布页面的发行说明中通常会链接到该指南。
发行说明：每个大版本在仓库GitHub发布页面的发行说明会总结破坏性变更。

以SDK仓库的文档为准。此处编写的任何版本差异内容都会随时间过期。目标平台对应的

platforms/

下的文件会列出需查阅的具体仓库。

Plan then migrate

先规划再迁移

Work in this order on every platform:

Bump the SDK to the new major version in a branch.
Fix compile errors using the CHANGELOG deprecations and removals as a guide.
Fix runtime behavior by reading the SDK logs on first launch.
Run the existing test suite and manual sandbox scenarios before merging.

在所有平台上按以下顺序操作：

在分支中将SDK升级至新的大版本。
以CHANGELOG中的弃用和移除内容为指导，修复编译错误。
通过首次启动时的SDK日志修复运行时行为问题。
在合并前运行现有测试套件并进行手动沙箱场景测试。

4. Implementation

4. 实施

Read the platform file that matches detection:

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

Each platform file covers both migration paths for that platform.

阅读与检测结果匹配的平台文件：

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

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

5. Verify

5. 验证

Do not declare migration done until:

The app builds on the new SDK version with no warnings from deprecated APIs you care about.
A sandbox purchase succeeds and the transaction shows up on the RevenueCat dashboard Sandbox view with the expected appUserID.
An existing subscriber from before the migration opens the app, and their entitlement state is correct. For Path A this proves the observer mode ingest worked. For Path B this proves the version bump did not drop state.
You have removed the debug log level override before shipping.

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

应用在新SDK版本上编译通过，且无您关注的已弃用API警告。
沙箱购买成功，且交易在RevenueCat控制台的沙箱视图中显示，且appUserID符合预期。
迁移前的现有订阅者打开应用后，其权益状态正确。对于路径A，这证明观察者模式的导入工作正常；对于路径B，这证明版本升级未丢失状态。
在发布前已移除调试日志级别覆盖设置。