将 Adapty React Native SDK 迁移至 v. 4.0

Adapty React Native SDK 4.0（测试版）引入了 flow 功能，并相应地重命名了付费墙 API。新 API 同时兼容全新的 Flow 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`
`createPaywallView(paywall)`	`createFlowView(flow)`
`AdaptyPaywallView`（组件）	`AdaptyFlowView`
`EventHandlers`（类型）	`FlowEventHandlers`
`onPaywallShown`	`onAppeared`
`onPaywallClosed`	`onDisappeared`
`onRenderingFailed`	`onError`
`AdaptyPaywallProduct` 保持原有命名——产品仍归属于流程，`getPaywallProducts` 现在接收 `AdaptyFlow` 参数。`getFlow` 和 `getFlowForDefaultAudience` 方法不再接受 `locale` 参数。视图方法 `present`、`dismiss`、`setEventHandlers`、`showDialog`，以及事件处理器 `onCloseButtonPress`、`onUrlPress`、`onCustomAction`、`onProductSelected`、`onPurchaseStarted`、`onPurchaseCompleted`、`onPurchaseFailed`、`onRestoreStarted`、`onRestoreCompleted`、`onRestoreFailed`、`onLoadingProductsFailed`、`onWebPaymentNavigationFinished` 和 `onAndroidSystemBack` 均与 v3 保持相同命名。部分默认行为有所变更——详见默认行为变更。

最低 iOS 版本

Adapty React Native SDK 4.0 将最低 iOS 部署目标从 iOS 13.0 提升至 iOS 15.0。升级前，请将您的 iOS 部署目标设置为 15.0 或更高版本。

安装

更新软件包

v4.0 为预发布版本，请固定精确版本号——npm 不会通过 caret/tilde 范围选取预发布版本：

npm install react-native-adapty@4.0.0
# or
yarn add react-native-adapty@4.0.0

iOS：原生 SDK 现在通过 Swift Package Manager 分发

CocoaPods 的 spec 仓库将于 2026 年 12 月变为只读，因此从 v4 开始，原生的 Adapty、AdaptyUI 和 AdaptyPlugin SDK 不再作为 CocoaPods 子依赖项引入 —— podspec 改为通过 Swift Package Manager（借助 spm_dependency 帮助函数）来拉取它们。这需要满足以下两个条件：

React Native 0.75 或更高版本 — 需要 spm_dependency podspec 辅助函数。在旧版本上，pod install 会报明确错误；请先升级 React Native，或继续使用 react-native-adapty 3.x。
动态框架 — SPM 依赖项需要动态链接。启用方式因 Expo 和裸 React Native 而有所不同。

Expo

添加 expo-build-properties 配置插件，并在 app.json（或 app.config.js）中将 iOS 框架设置为动态：

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

然后安装插件并重新生成原生项目：

npx expo install expo-build-properties
npx expo prebuild --clean

Bare React Native

在你的 iOS target 中添加动态框架，然后重新安装 pods：

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

如果你之前通过 CocoaPods 子依赖的方式引入了 Adapty、AdaptyUI 或 AdaptyPlugin，请先从 Podfile 中删除所有显式的 pod 'Adapty'、pod 'AdaptyUI' 或 pod 'AdaptyPlugin' 行。

从默认静态链接切换到动态框架可能与尚不支持模块化头文件的库产生冲突，且与 Flipper 不兼容。如果遇到构建问题，请参阅这篇关于将 Swift Package Manager 与 React Native 库集成的文章。

完整的安装步骤，请参阅安装 Adapty SDK。

获取流程

getPaywall → getFlow

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

- const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');

getPaywallForDefaultAudience 也以同样的方式重命名：

- const paywall = await adapty.getPaywallForDefaultAudience('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlowForDefaultAudience('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` 检查。
`requestLocale`	已移除	语言区域不再是模型的一部分。
（新增）	`paywalls: AdaptyFlowPaywall[]`	每个条目代表流程中的一个付费墙变体。
（新增）	`responseCreatedAt: number`	服务器响应时间戳，单位为毫秒。
产品标识符已从流程移至每个实验变体：

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

Web 付费墙方法

openWebPaywall 和 createWebPaywallUrl 方法名保持不变，但第一个参数现在是 AdaptyFlowPaywall（流程变体），而非 AdaptyPaywall。你仍然可以传入 AdaptyPaywallProduct。

  const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
- await adapty.openWebPaywall(paywall);
+ await adapty.openWebPaywall(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。返回的控制器方法（present、dismiss、setEventHandlers、showDialog）保持不变：

- import { createPaywallView } from 'react-native-adapty';
+ import { createFlowView } from 'react-native-adapty';

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

AdaptyPaywallView → AdaptyFlowView

如果你使用 React 组件渲染，请将其重命名并传入 flow prop：

- import { AdaptyPaywallView } from 'react-native-adapty';
+ import { AdaptyFlowView } from 'react-native-adapty';

- <AdaptyPaywallView paywall={paywall} /* … */ />
+ <AdaptyFlowView flow={flow} /* … */ />

使用 createFlowView 创建的流程视图只能使用一次：调用 dismiss() 后，该视图会被销毁，如需再次展示流程，请重新调用 createFlowView。嵌入式 AdaptyFlowView 通过卸载组件来关闭——从处理函数中返回 true 并不会关闭嵌入式视图，因此请改为修改自身状态，例如在 onCloseButtonPress 中进行处理。

处理事件

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

- onPaywallShown: () => { /* … */ },
+ onAppeared: () => { /* … */ },

- onPaywallClosed: () => { /* … */ },
+ onDisappeared: () => { /* … */ },

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

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

onDisappeared 仅在通过 createFlowView().present() 以模态方式呈现的 flow 中触发。AdaptyFlowView 组件不将其作为 prop 暴露——如需关闭嵌入式视图，请通过卸载组件来实现。

v4 还新增了一些可按需启用的功能：

adapty.openWebUrl(url, openIn?) 和 adapty.requestAppReview() 方法 —— 这两个方法支持默认的 onUrlPress 和 onRequestAppReview 处理器，因此 URL 跳转和应用评价弹窗均可开箱即用地原生处理。只有在你覆盖这些处理器时，才需要直接调用它们。
通过新的 onObserverPurchaseInitiated / onObserverRestoreInitiated 处理器，在流程中支持观察者模式下的购买处理。详见在观察者模式下处理购买。

已移除和废弃的 API

setFallbackPaywalls → setFallback

setFallbackPaywalls 已被移除。请使用 setFallback，参数保持不变：

- await adapty.setFallbackPaywalls(fileLocation);
+ await adapty.setFallback(fileLocation);

已移除的导出

这些符号已不再从 react-native-adapty 导出，请移除相关导入：

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

activate: lockMethodsUntilReady

lockMethodsUntilReady 已被移除，该行为现在默认始终开启。请从 activate 调用中删除它——保留该参数将导致编译错误：

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

makePurchase：Android 订阅更新

原有的 Android 订阅更新扁平结构已移除。请将 oldSubVendorProductId 和 prorationMode 移入嵌套的 subscriptionUpdateParams 对象中，并将 isOfferPersonalized 保留在顶层。完整示例请参阅发起购买。

Android：安全区域内边距

Android 布尔资源 <bool name="adapty_paywall_enable_safe_area_paddings">…</bool> 已被移除。请从 res/values/bools.xml 中删除该条目，并在创建流程视图时通过 enableSafeArea 参数在运行时控制安全区域内边距。该参数在模态展示时默认为 true，在嵌入式组件中默认为 false。

模拟模式

如果你在模拟模式下运行 SDK（Expo Go 或 Web 预览），请将模拟配置的键名 paywalls 改为 flows。

默认行为变更

以下变更不会引起编译错误，请在运行时进行测试：

onAndroidSystemBack: 默认行为已从关闭视图改为保持视图打开。若要恢复之前的行为，请在处理程序中返回 true。
onPurchaseCompleted: 默认行为已从关闭视图（除非用户取消购买）改为始终保持视图打开。若要恢复之前的行为，请在处理程序中返回 purchaseResult.type !== 'user_cancelled'。
onRestoreCompleted: 默认行为已从恢复成功后关闭视图改为保持视图打开。若要恢复之前的行为，请在处理程序中返回 true。
onUrlPress: 现在默认通过原生层打开 URL，遵循看板中设置的应用内或外部浏览器选项。如需自行控制 URL 的打开方式，请覆盖该处理程序。

用户引导 API 弃用

旧版用户引导 API 已在 v4.0 中弃用，请改用 Flow Builder。该 API 目前仍可正常使用，IDE 会通过 @deprecated 注解标记已弃用的符号——不会产生任何运行时警告。这些符号将在未来版本中移除，请提前将您的用户引导迁移至 Flow Builder。

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