将 Adapty Capacitor SDK 迁移至 v. 4.0

Adapty Capacitor SDK 4.0（测试版）引入了流程功能，并对付费墙 API 进行了相应重命名。新 API 同时兼容全新的 Flow Builder 和现有的 Paywall Builder，无需在 Adapty 看板侧做任何配置变更。

快速参考

v3	v4
`adapty.getPaywall({ placementId, locale?, params? })`	`adapty.getFlow({ placementId, params? })`
`adapty.getPaywallForDefaultAudience({ placementId, locale?, params? })`	`adapty.getFlowForDefaultAudience({ placementId, params? })`
`adapty.getPaywallProducts({ paywall })`	`adapty.getPaywallProducts({ flow })`
`adapty.logShowPaywall({ paywall })`	`adapty.logShowFlow({ flow })`
`AdaptyPaywall` (类型)	`AdaptyFlow` + `AdaptyFlowPaywall`
`createPaywallView(paywall, params?)`	`createFlowView(flow, params?)`
`PaywallViewController`	`FlowViewController`
`EventHandlers` (类型)	`FlowEventHandlers`
`CreatePaywallViewParamsInput`	`CreateFlowViewParamsInput`
`onRenderingFailed`	`onError`
`AdaptyPaywallProduct` 保持其名称不变——产品仍属于一个 flow，`getPaywallProducts` 也保持其名称，现在接受一个 `AdaptyFlow` 参数。`getFlow` 和 `getFlowForDefaultAudience` 方法不再接受 `locale` 参数。购买和用户画像相关 API（`makePurchase`、`restorePurchases`、`getProfile`、`identify`、`updateProfile`）以及通过 `setFallback` 设置的备用付费墙均保持不变。视图方法 `present`、`dismiss`、`setEventHandlers`、`showDialog`，以及事件处理器 `onCloseButtonPress`、`onUrlPress`、`onCustomAction`、`onProductSelected`、`onPurchaseStarted`、`onPurchaseCompleted`、`onPurchaseFailed`、`onRestoreStarted`、`onRestoreCompleted`、`onRestoreFailed`、`onLoadingProductsFailed`、`onWebPaymentNavigationFinished` 和 `onAndroidSystemBack` 与 v3 中的名称相同。用户引导方法仍可使用，但已被弃用——详见用户引导 API 弃用说明。部分默认行为已发生变更——详见默认行为变更。

最低版本要求

运行时要求与 v3.16+ 保持不变：iOS 15.0、Android minSdk 24 以及 Capacitor 8，无需更改部署目标。

有一项新的构建要求：Xcode 26 或更高版本 —— 此版本捆绑的原生 Adapty iOS SDK 4.0.0-beta.2 使用 Swift tools 6.2。

v4 捆绑了原生 Adapty SDK iOS 4.0.0-beta.2 和 Android BOM 4.0.0-beta.1。

安装

更新包

v4.0 是预发布版本，请固定精确版本号——npm 不会通过脱字符/波浪号范围选择预发布版本：

npm install @adapty/capacitor@4.0.0-beta.1

然后同步原生项目：

npx cap sync

iOS：仅支持 Swift Package Manager

CocoaPods 的 spec 仓库将于 2026 年 12 月进入只读模式，因此从 v4 起 AdaptyCapacitor.podspec 已被移除，SDK 在 iOS 上仅通过 Swift Package Manager（SPM）安装。你的应用 iOS 工程必须使用 Capacitor 的 SPM 集成方式：

新项目：使用 SPM 包管理器添加 iOS 平台：

npx cap add ios --packagemanager SPM

现有 CocoaPods 项目：按照 Capacitor 关于在现有项目中使用 SPM 的指南迁移 iOS 项目。

参阅安装 Adapty SDK 了解完整配置步骤。

获取流程

getPaywall → getFlow

返回类型从 AdaptyPaywall 变更为 AdaptyFlow，同时移除了 locale 选项——渲染 flow 时，语言环境会自动解析；对于自定义付费墙，所有语言环境均通过 flow.remoteConfigs 返回：

- const paywall = await adapty.getPaywall({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallForDefaultAudience 以相同方式重命名：

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID' });

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts 保持原名，但现在接收一个 AdaptyFlow：

- const products = await adapty.getPaywallProducts({ paywall });
+ const products = await adapty.getPaywallProducts({ flow });

数据模型

getFlow 返回的是 AdaptyFlow 而非 AdaptyPaywall，对象结构也发生了变化：

v3 `AdaptyPaywall` 字段	v4 `AdaptyFlow` 字段	操作
`remoteConfig?`（单个）	`remoteConfigs?: AdaptyRemoteConfig[]`（数组）	一个流程为每种已配置的语言携带一个远程配置。读取与用户匹配的那个：`flow.remoteConfigs?.find((c) => c.lang === 'en')`。
`products`	`flow.paywalls[i].productIdentifiers`	产品标识符现在位于每个流程变体上，而不是在流程本身。
`webPurchaseUrl?`	`flow.paywalls[i].webPurchaseUrl`	从流程移至每个付费墙变体。
`version?: number`	`flowVersionId?: string`	已重命名，类型从 `number` 更改为 `string`。
`hasViewConfiguration`	已移除	从代码中删除所有 `hasViewConfiguration` 检查——`createFlowView` 现在会直接抛出异常（参见展示流程）。
`requestLocale`	已移除	语言区域不再是模型的一部分。
(新增)	`paywalls: AdaptyFlowPaywall[]`	每个条目是流程中的一个付费墙变体。
(新增)	`responseCreatedAt: number`	服务器响应时间戳，单位为毫秒。
`hasViewConfiguration` 和 `requestLocale` 保留在 `AdaptyOnboarding` 上——只有流程模型移除了它们。

产品标识符从流程移至每个实验变体：

- const ids = paywall.products;
+ const ids = flow.paywalls[0].productIdentifiers;

Web 付费墙方法

openWebPaywall 和 createWebPaywallUrl 保持原名不变，但 paywallOrProduct 选项现在接收 AdaptyFlowPaywall（流程变体）而非 AdaptyPaywall。你仍然可以传入 AdaptyPaywallProduct。在读取第一个条目之前，请先确认 flow.paywalls 非空：

  const flow = await adapty.getFlow({ placementId: 'YOUR_PLACEMENT_ID' });
- await adapty.openWebPaywall({ paywallOrProduct: paywall });
+ await adapty.openWebPaywall({ paywallOrProduct: flow.paywalls[0] });

跟踪流程查看次数

logShowPaywall → logShowFlow

logShowPaywall 已重命名为 logShowFlow，现在接受一个 AdaptyFlow 参数。该事件仍针对相同的实验变体进行记录，因此现有的漏斗和 A/B 测试数据图表无需修改看板即可继续正常使用。

- await adapty.logShowPaywall({ paywall });
+ await adapty.logShowFlow({ flow });

与 v3 一样，当展示由 Flow Builder 或付费墙编辑工具渲染的流程或付费墙时，无需手动调用此方法——Adapty 会自动追踪这些视图。

显示流程

createPaywallView → createFlowView

重命名工厂函数并传入 AdaptyFlow。返回的控制器从 PaywallViewController 更名为 FlowViewController，但其方法（present、dismiss、setEventHandlers、showDialog）保持不变。参数类型从 CreatePaywallViewParamsInput 更名为 CreateFlowViewParamsInput：

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

如果 flow 未配置视图，createFlowView 会抛出 AdaptyError——这取代了 v3 中的 hasViewConfiguration 检查：

- if (paywall.hasViewConfiguration) {
-   const view = await createPaywallView(paywall);
-   await view.present();
- }
+ try {
+   const view = await createFlowView(flow);
+   await view.present();
+ } catch (error) {
+   // the flow has no view configured, or view creation failed
+ }

Flow 视图是一次性的：调用 dismiss() 后，视图会被销毁，其事件处理器也会被清除。如需再次展示该 flow，请重新调用 createFlowView。

Android 安全区域内边距

CreateFlowViewParamsInput 新增了一个参数：enableSafeArea，用于在运行时控制 Android 安全区域内边距。该参数嵌套在 android 键下，默认值为 true：

const view = await createFlowView(flow, {
  android: { enableSafeArea: true },
});

处理事件

事件处理器接口从 EventHandlers 重命名为 FlowEventHandlers，同时有一个回调也进行了重命名。现有的处理器逻辑无需修改代码，只需重命名即可：

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

所有其他事件处理函数保持原有名称不变。其中两个新增了第二个参数：onPurchaseCompleted 现在是 (purchaseResult, product)，onPurchaseFailed 现在是 (error, product)，其中 product 是涉及的 AdaptyPaywallProduct。完整列表请参阅处理 flow 与付费墙事件。

v4 还新增了一些可选功能：

adapty.openWebUrl({ url, openIn }) 和 adapty.requestAppReview() 方法——这两个方法支持默认的 onUrlPress 和 onRequestAppReview 处理器，因此 URL 和应用评价提示默认即可原生处理。仅在覆盖这些处理器时才需直接调用它们。
通过新的 onObserverPurchaseInitiated / onObserverRestoreInitiated 处理器，在流程中支持观察者模式下的购买处理。详见在观察者模式下展示流程。

默认行为变更

这些变更不会导致编译错误，请在运行时进行测试：

onAndroidSystemBack：默认行为已从关闭视图改为保持打开状态。若要恢复之前的行为，请在处理程序中返回 true。
onPurchaseCompleted：默认行为已从关闭视图（用户取消购买时除外）改为始终保持打开状态。若要恢复之前的行为，请在处理程序中返回 purchaseResult.type !== 'user_cancelled'。
onRestoreCompleted：默认行为已从恢复成功后关闭视图改为保持打开状态。若要恢复之前的行为，请在处理程序中返回 true。
onUrlPress：默认行为现在通过原生层打开 URL，遵循看板中配置的应用内浏览器或外部浏览器设置。如需自行处理 URL 的打开方式，请覆盖该处理程序。
视图仅可使用一次：调用 dismiss() 后，视图将被销毁。如需再次展示该流程，请重新调用 createFlowView。

已移除的 API

已移除的导出

以下符号已不再从 @adapty/capacitor 中导出，请移除相关导入：

AdaptyPaywall：请改用 AdaptyFlow 和 AdaptyFlowPaywall。
ProductReference：请改用 AdaptyProductIdentifier，从 flow.paywalls[i].productIdentifiers 中读取。
AdaptyPaywallBuilder：已移除。流程和付费墙现在以原生方式渲染。
AdaptyAndroidSubscriptionUpdateParameters：请改用嵌套的 android 购买参数结构（详见下文）。

activate: lockMethodsUntilReady

lockMethodsUntilReady（在 v3 中已被弃用为空操作）现已移除。请从 activate 调用中删除它——保留该参数将无法编译：

- await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY', params: { lockMethodsUntilReady: true } });
+ await adapty.activate({ apiKey: 'PUBLIC_SDK_KEY' });

makePurchase：Android 参数

已废弃的 MakePurchaseParamsInput 扁平 Android 格式已被移除，现在只保留嵌套形式。请将所有 Android 购买参数迁移到 params: { android: { ... } } 中。完整示例请参阅发起购买。

用户引导 API 弃用

旧版用户引导 API 已在 v4.0 中弃用，请改用 Flow Builder。该 API 目前仍可正常使用，但将在未来版本中移除，请提前将您的用户引导迁移至 Flow Builder。

已弃用的符号：getOnboarding、getOnboardingForDefaultAudience、createOnboardingView 和 OnboardingViewController。