从 RevenueCat 迁移共分八个步骤。编码代理会完成大部分工作：通过 Adapty CLI 运行迁移，并替换应用中的 RevenueCat SDK。而代理无法触及的部分——密钥、RevenueCat、App Store Connect 和 Google Cloud 中的设置——则需要你来完成。

1. 了解核心差异。
2. 将产品目录迁移到 Adapty。
3. 迁移付费墙设计，如果你的 offerings 将变为流程。
4. 使用你的编程助手替换 RevenueCat SDK。
5. 迁移集成。
6. 将商店事件转发给 Adapty。
7. 测试并发布新版本应用。
8. （可选）导入历史交易记录。

在发布集成了 Adapty SDK 的新版本应用之前，请务必查看我们的发布清单。

了解核心差异

Adapty 与 RevenueCat 的 SDK 设计思路相近。最大的区别在于网络使用方式和响应速度：Adapty SDK 的设计目标是在你需要时尽可能快地返回信息。例如，在请求付费墙时，你会先获取远程配置以预构建用户引导或付费墙，然后通过专门的请求来获取产品信息。

命名方式略有不同：

RevenueCat	Adapty
Package	产品
Offering	付费墙
Paywall	流程
Entitlement	访问等级

Adapty 有一个版位的概念。它是应用中用户可以进行购买的逻辑位置。大多数情况下，你会有一到两个版位：

• 用户引导（因为 80% 的购买都发生在这里）；
• 通用版位（在用户引导结束后，在设置页面或应用内展示）。

将您的产品目录迁移至 Adapty

目录迁移会基于您的 RevenueCat 项目创建一个新的 Adapty 应用：将权益转换为访问等级，将软件包转换为产品，并为每个 Offering 创建一个包含付费墙或流程的版位。

开始之前

• 使用能够运行终端命令的编程智能体，例如 Claude Code、Codex 或 Cursor。
• 在智能体使用的终端中，安装 Adapty CLI 并登录。
• 在 RevenueCat 中，为要迁移的项目创建一个 Secret API Key（v2）。
• 检查商店。迁移仅支持 App Store 和 Google Play 应用。

创建 RevenueCat 密钥 API

Adapty 使用密钥 API 读取你要迁移的 RevenueCat 项目目录。由于密钥属于单个项目，请在对应项目中创建该密钥。

1. 要打开密钥列表，请在 RevenueCat 看板中打开项目，然后进入 API keys。
2. 要创建密钥，请点击 New secret API key。
3. 要配置密钥，输入一个名称（例如 Adapty migration），并在 API version 中选择 V2。
4. 要让 Adapty 读取目录，将 Project configuration permissions 设置为 Read only。Adapty 不需要其他权限。
5. 要创建密钥，请点击 Generate，然后复制它。

当迁移工具要求提供密钥时，将其粘贴到打开的 Adapty 看板页面中。

运行目录迁移

1. 要开始迁移，请向您的智能体发出请求：

   Migrate my RevenueCat project to a new Adapty app called "Acme Fitness" with the Adapty CLI.

2. 要连接 RevenueCat，请将密钥粘贴到 Agent 打开的 Adapty 看板页面中。密钥直接发送至 Adapty，不会经过 Agent 或 CLI。

3. 要选择迁移内容，请告诉 Agent 哪些 RevenueCat 应用属于同一产品——通常是同一产品的各平台版本——它们将合并为一个 Adapty 应用。

4. 要确定映射关系，请回答 Agent 关于无法自动映射实体的提问。对于每个 offering，选择其版位所包含的内容：由应用自行渲染的付费墙，还是来自流程与付费墙编辑工具的流程。对于带有 RevenueCat 付费墙的 offering，Adapty 会建议使用流程。

   Warning

决策一旦做出即不可更改。当所有实体都有决策后，Adapty 将创建目录，之后无法更改映射关系。 :::

Adapty 会按顺序创建访问等级、产品、付费墙与流程以及版位。如果某些步骤失败，代理会告知原因。当所有实体都成功创建到 Adapty 后，迁移即完成。

5. 要让新应用能够验证购买，请在 Adapty 看板中将其连接到应用商店：App Store 和 Google Play。

RevenueCat 实体与 Adapty 的对应关系

• 权限标识符对应访问等级 ID，即 customerInfo.entitlements["premium"] 对应 profile.accessLevels["premium"]。
• 不授予任何权限的产品将授予 premium 访问等级。
• 套餐标识符对应版位 ID。
• 套餐元数据对应付费墙或流程的远程配置，最大支持 256 KB。

目录迁移不包含的内容

• 没有产品的 Offering。
• App Store 产品 ID 被 Adapty 拒绝的产品，例如 ID 中包含冒号或空格。Agent 会告知你具体是哪些，无需额外处理。
• App Store 和 Google Play 以外应用商店中的应用。
• Integrations：请单独迁移。

迁移付费墙设计

目录迁移创建的每个流程都会发布一个空白屏幕，覆盖在产品列表上方。要将您的 RevenueCat 付费墙设计迁移到这些流程中，请向您的 AI 助手发送以下指令：

Migrate my RevenueCat paywall designs to my Adapty app "Acme Fitness" with the Adapty CLI.

AI 助手会逐一重建各个流程，并在您确认后发布每个流程。它还会列出需要您自行添加的内容，例如视频和自定义字体。它通过您的 RevenueCat 密钥 API Key 读取设计数据，因此在设计迁移完成之前请保留该密钥。

替换 RevenueCat SDK

编码代理会使用迁移创建的目录 ID，将应用代码中的 RevenueCat SDK 替换为 Adapty SDK。每次运行迁移一个代码库：如果应用有独立的 iOS 和 Android 项目，需分别在各项目中运行。

开始之前，请先提交或暂存应用仓库中的现有改动，以便迁移内容保持为一个可审查的差异提交。

1. 要开始代码迁移，请在应用仓库的根目录中打开你的代理并输入：

   Migrate the app code in this repository from RevenueCat to Adapty with the Adapty CLI, for my Adapty app "Acme Fitness".

   如果 Agent 要求你重启以加载 Adapty 技能，请重启并重复该请求。

2. 如果某个流程的设计尚未迁移，请告知 Agent：在此之前，应用是显示该流程，还是保留自己的付费墙界面。

3. 完成代码迁移后，查看 adapty-migrate 分支上的变更，然后处理项目根目录下的 ADAPTY_SETUP.md。该文件列出了 Agent 留给你的待办事项。

迁移您的集成

您的智能体会在应用代码中找到分析、归因和消息推送工具，并告知如何在 Adapty 中逐一完成配置。它不会修改任何文件。您可以这样提问：

Find the integrations in my app code to set up in my Adapty app "Acme Fitness", with the Adapty CLI.

如果代码库中只包含一个平台的代码，请告知 agent 另一个平台的代码位置。然后按照将集成迁移到 Adapty 中的说明配置集成。Webhook、Slack 和云存储导出不在应用代码中：请在 RevenueCat 的 Integrations 页面查找。

将商店事件转发至 Adapty

App Store 和 Google Play 通过通知将续订、取消和退款等事件上报至你的服务器，包括发生在应用外部的事件。两项迁移操作可将 Adapty 接入这些通知，同时 RevenueCat 仍会继续接收每一个事件，确保在用户迁移到新版应用期间，双方数据始终保持同步。

请在目录迁移完成后再启动这两项操作。Adapty 将从你在该步骤中选择的 RevenueCat 应用中获取 bundle ID 和包名。

转发 App Store 事件

Adapty 接收 App Store 通知并将每条通知转发给 RevenueCat。

在开始之前，请在 App Store Connect 中创建一个 In-App Purchase key，并记录其 Issuer ID 和 Key ID。

1. 要开始转发，请向你的 agent 发送以下请求：

   Forward App Store events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. 为了让 Adapty 访问 App Store 事件，请在代理打开的 Adapty 看板页面中上传 .p8 文件，并填写 Issuer ID 和 Key ID。密钥将直接发送给 Adapty，不会经过代理或 CLI。

3. 为了让 RevenueCat 继续接收 App Store 事件，请将 RevenueCat 通知 URL 提供给代理。在 RevenueCat 中，打开你的 iOS 应用，然后从 Apple Server to Server notification settings 中复制 Apple Server Notification URL。该 URL 以 https://api.revenuecat.com/v1/incoming-webhooks/ 开头。

4. 为了将 App Store 指向 Adapty，请在 App Store Connect 中打开你的应用，然后前往 App Information > App Store Server Notifications。将 Production Server URL 和 Sandbox Server URL 均设置为代理提供给你的 Adapty URL，并选择 Version 2 通知。详情请参阅启用 App Store 服务器通知。此时转发至 RevenueCat 的功能已开启，不会丢失任何事件。

5. 要验证连接，请告知代理 URL 已设置完成。Adapty 将向 App Store 请求测试通知并等待接收。如果通知未能送达，代理会告诉你原因。

转发 Google Play 事件

Google Play 会将通知发送到 Pub/Sub 主题。Adapty 以第二订阅者的身份订阅 RevenueCat 已使用的主题，因此 RevenueCat 仍可继续接收事件。

1. 如需开始转发，请向你的 Agent 发送以下请求：

   Forward Google Play events for my Adapty app "Acme Fitness" to Adapty, and keep RevenueCat receiving them.

2. 要让 Adapty 访问该主题，请为 RevenueCat 使用的服务账号创建一个 JSON 密钥。在 Google Cloud 控制台中，前往 IAM & Admin > Service Accounts，打开该账号（通常为 revenuecat-service-account），然后依次点击 Keys > Add key，选择 JSON。新密钥不会影响 RevenueCat 的正常使用。详细步骤请参阅 Google 的指南：创建服务账号密钥。

3. 要上传密钥，请在代理打开的 Adapty 看板页面中，将文件上传至 Google Play service account key (JSON)。密钥将直接发送至 Adapty，不会经过代理或 CLI。

4. 要让 Adapty 订阅该主题，请将主题 ID 提供给代理。在 RevenueCat 中打开您的 Google Play 应用设置，然后从 Google developer notifications 中复制 Topic ID。Google Play Console 在 Monetize > Monetization setup > Topic name 处也可看到相同的值。

   Adapty 订阅该主题，然后发布一条测试通知并等待接收。如果未能收到，代理会告知原因。

5. 如果测试因权限问题失败，请在主题所在项目中为服务账号授予 Pub/Sub Editor 角色，或在该主题上授予 Pub/Sub Subscriber 角色并在密钥所在项目中授予 Pub/Sub Editor 角色。然后让代理重新检查。

测试并发布应用的新版本

如果你看到这里，说明你已经完成了：

• 将商品目录迁移至 Adapty
• 如果你使用 flow，已迁移付费墙设计
• 将 RevenueCat SDK 替换为 Adapty
• 已按照编程 Agent 生成的 ADAPTY_SETUP.md 完成配置
• 在 Adapty 中设置好集成
• 将 App Store 和 Google Play 事件转发至 Adapty
• 完成沙盒内购测试
• 发布应用新版本

如果以上各项均已确认，只需在沙盒环境中完成一次测试内购，然后发布应用即可。

（可选）导入历史交易记录

导入操作会将用户的付款历史填充到用户画像和数据图表中，不会影响任何人的访问权限。

通过两次迁移操作，可将历史记录导入到目录迁移所创建的应用中。如果您的 RevenueCat 套餐包含云导出功能，请使用云导出。

使用 RevenueCat 云端导出

RevenueCat 每天将数据导出到 Adapty 为你的应用准备的存储桶中，Adapty 会导入收到的每个文件。

1. 要开始导入，请向你的 agent 发送请求：

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" with a Cloud Export.

2. 要连接导出，请将 RevenueCat 的 External ID 提供给 agent。在 RevenueCat 中，打开 Scheduled Data Exports 设置，选择 IAM Role (ARN) 作为凭证类型，并复制 RevenueCat 显示的 External ID。External ID 不是保密信息。

3. 要完成导出设置，请在 RevenueCat 中输入 agent 提供的 bucket、region 和 role ARN。开启 Receive new and updated transactions only。否则，RevenueCat 每天会导出完整的历史记录，而 Adapty 会导入每一个文件。

RevenueCat 最多需要 24 小时才能交付第一个文件，Adapty 每小时检查一次存储桶中的新文件。迁移会在 Adapty 导入第一个文件后一周自动完成。每个导入用户画像的 Customer User ID 为 rc_last_seen_app_user_id_alias。

通过支持团队

如果您的 RevenueCat 方案不包含云端导出功能，可使用此方式：由 RevenueCat 支持团队向您发送导出文件，再由 Adapty 支持团队负责导入。

1. 要开始导入，请向您的代理发送以下请求：

   Import the RevenueCat transaction history into my Adapty app "Acme Fitness" through support.

2. 如需请求数据导出，请将智能助手给出的第一条消息发送给 RevenueCat 支持团队。

3. 如需导入数据，请将 RevenueCat 发送的文件转发给 Adapty 支持团队，并附上第二条消息。请原封不动地附上文件，不要打开、重新保存或合并——任何修改都会导致导入所需的列格式发生变化。

导入内容说明

以下数据将在每笔交易中导入到 Adapty：

参数	描述
user_id	客户用户 ID，即用户在 Adapty 和您系统中的主要标识符。
apple_original_transaction_id	对于订阅链，这是原始交易的购买日期，通过 store_original_transaction_id 关联。
google_product_id	Google Play 商店中的产品 ID。
google_purchase_token	Google Play 为每笔交易提供的唯一标识符，用于验证。
country	用户所在国家/地区。
created_at	用户创建的日期和时间。
subscription_expiration_date	订阅到期的日期和时间。
email	终端用户的电子邮件地址。
phone_number	终端用户的电话号码。
idfa	广告标识符（IDFA），由 Apple 分配给用户设备。
idfv	供应商标识符（IDFV），由同一开发者分配给其所有应用，并在该设备上的这些应用间共享。
advertising_id	Android 系统提供的唯一标识符，广告商可用于追踪。
attribution_channel	营销渠道名称。
attribution_campaign	营销活动名称。
attribution_ad_group	归因广告组。
attribution_ad_set	归因广告集。
attribution_creative	归因素材关键词。

此外，以下集成的集成标识符也将被导入：Amplitude、Mixpanel、AppsFlyer、Adjust 和 FacebookAds。

哪些内容无法传达

• 导入时，每笔交易都会向应用商店重新验证，应用商店无法识别的记录将被丢弃。
• 没有真实应用商店交易 ID 的记录——例如 RevenueCat 的促销活动或手动授予的权益——将作为无交易的用户画像导入。如需恢复此类用户的访问权限，请通过服务端 API 为其授予访问等级。
• 退款和账单问题历史不会原样迁移：退款仅保留取消日期，订阅的账单问题状态以导入时的状态为准，而非历史日期。

常见问题

我已成功安装 Adapty SDK 并发布了包含它的新版本。那些没有更新到包含 Adapty SDK 版本的老订阅用户会怎样？

大多数用户会在夜间充电时让手机自动更新所有应用，因此这通常不是问题。确实可能还有少量付费订阅用户没有升级，但他们仍然可以访问高级内容。你不需要为此担心，也无需强制他们更新。

我需要尽快从 RevenueCat 导出历史数据吗？还是说不导出就会丢失？

不需要那么着急，先发布集成了 Adapty SDK 的新版本，之后再导入历史数据即可。我们会还原用户的付款历史，并填充用户画像和数据图表。

我使用了 MMP（AppsFlyer、Adjust 等）和分析工具（Mixpanel、Amplitude 等），如何确保一切正常运行？

您需要先通过我们的 SDK 将第三方服务的 ID 传给我们，这样我们才能向这些服务发送数据。请参阅归因集成和分析工具集成的相关指南。对于历史数据和存量用户，请务必将您从 RevenueCat 导出的数据中提取出对应的 ID 传给我们。