Adapty Capacitor SDK 4.1.1 是 4.x 系列的当前稳定版本——4.0 仅作为 Beta 版发布，因此如果你目前使用的是 3.x，请直接迁移至 4.1.1。本指南涵盖完整的迁移内容：4.0 中引入的流程，以及 4.1.1 在此基础上的变更。

4.x 系列引入了流程功能，并相应地重命名了付费墙相关 API。新 API 支持流程，同时也兼容旧版编辑工具构建的付费墙——无需在 Adapty 看板侧做任何配置变更。此外，4.1.1 将 Adapty Attribution 改为按需启用，重命名了外部归因方法，更改了备用文件格式，并新增了 App Store 应用内购促销功能。

快速参考

v3	v4.1.1
默认启用 Adapty 归因	默认禁用 — 通过 adaptyAttributionEnabled: true 启用
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
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders
AttributionSource	AdaptyExternalAttributionProvider
为 3.x 下载的备用文件	新备用文件格式 — 请重新下载文件
应用内促销购买自动完成，无法拦截	'onPromotedPurchaseReceived' 事件和 adapty.makePromotedPurchase({ product }) 将完成控制权交给您的应用

AdaptyPaywallProduct 保持原名——产品仍属于某个流程，getPaywallProducts 也保持原名，现在接受一个 AdaptyFlow 参数。getFlow 和 getFlowForDefaultAudience 方法不再接受 locale 参数——改为传给 createFlowView。购买和用户画像相关的 API（makePurchase、restorePurchases、getProfile、identify、updateProfile）及 setFallback 保持相同的签名，但备用付费墙文件本身需要重新下载——请参阅备用文件。视图方法 present、dismiss、setEventHandlers、clearEventHandlers、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 使用 Swift tools 6.2。

安装

更新软件包

npm install @adapty/capacitor@latest

然后同步原生项目：

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 了解完整配置步骤。

⚠️ Adapty 归因默认已禁用

在早期版本中，SDK 会自动为 Adapty Attribution 注册安装信息。从 SDK 4.1.1 版本起，此功能默认关闭：SDK 不再注册安装信息，'onInstallationDetailsSuccess' 和 'onInstallationDetailsFail' 事件不会触发，getCurrentInstallationStatus 返回 not_available 状态。

如果你使用 Adapty Attribution，请在激活 SDK 时启用该功能：

  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
+     adaptyAttributionEnabled: true,
    },
  });

如果您不使用 Adapty 归因功能，则无需进行任何更改。

获取流程

getPaywall → getFlow

返回类型从 AdaptyPaywall 变更为 AdaptyFlow，locale 选项从获取调用移至 createFlowView；对于自定义付费墙，所有语言环境均在 flow.remoteConfigs 中返回：

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

locale 在 createFlowView 中仍为可选参数：省略它则视图以 en 渲染，若流程没有 en 则使用该流程的默认本地化。由于这个回退机制，视图实际渲染的本地化可能与你所请求的不同——新增的 FlowViewController.locale 属性会报告实际使用的本地化。详见本地化与语言区域代码。

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 });

备用文件

备用文件 的格式在 4.0 版本中发生了变化，在 4.1.1 版本中再次更新。请从 Placements > Fallbacks 重新下载该文件并将其打包到应用中，即使你已经为 4.0 测试版下载过。

数据模型

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

v3 AdaptyPaywall 字段	v4 AdaptyFlow 字段	操作
remoteConfig?（单个）	remoteConfigs?: AdaptyRemoteConfig[]（数组）	一个流程包含每种已配置语言的一份远程配置。读取与用户匹配的那一份：flow.remoteConfigs?.find((c) => c.lang === 'en')。
productIdentifiers	flow.paywalls[i].productIdentifiers	产品标识符现在位于每个流程变体上，而非流程本身。
products（在 v3 中已弃用）	已移除	使用 flow.paywalls[i].productIdentifiers，或调用 getPaywallProducts(flow) 获取完整产品信息。ProductReference 已作为公开类型移除。
webPurchaseUrl?	flow.paywalls[i].webPurchaseUrl	从流程移至每个付费墙变体。
version?: number	flowVersionId?: string	已重命名，类型从 number 改为 string。
requestLocale	已移除	语言区域设置不再是模型的一部分。
（新增）	paywalls: AdaptyFlowPaywall[]	每个条目对应流程中的一个付费墙变体。
（新增）	responseCreatedAt: number	服务器响应时间戳，单位为毫秒。

requestLocale 仍保留在 AdaptyOnboarding 上——只有 flow 模型移除了它。

产品标识符从 flow 移至每个 variation：

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

如果你的代码仍在读取 paywall.products——该属性在 v3 中已废弃，现已彻底移除——请改用 productIdentifiers，或在需要完整产品信息（而非仅标识符）时调用 getPaywallProducts(flow)。

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 相同，当展示由 Adapty 渲染的流程或付费墙时，无需手动调用此方法——Adapty 会自动追踪这些浏览记录。

显示流程

createPaywallView → createFlowView

将工厂函数重命名，并传入 AdaptyFlow。返回的控制器从 PaywallViewController 重命名为 FlowViewController，但其方法（present、dismiss、setEventHandlers、clearEventHandlers 和 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();

新增参数

CreateFlowViewParamsInput 保留了 v3 的所有参数（prefetchProducts、loadTimeoutMs、customTags、customTimers、customAssets、productPurchaseParams），并新增了以下三个：

参数	描述
locale	渲染流程时所使用的本地化语言。该参数已从 getPaywall 移至此处——详见 getPaywall → getFlow。
customLayoutId	流程布局配置中某个布局的自定义 ID。传入该 ID 可渲染指定布局，而非由 SDK 根据设备类型和屏幕尺寸自动选择的布局。如果没有布局与该 ID 匹配，调用将失败并返回无视图配置错误。Flow & Paywall Builder 目前尚未支持分配自定义布局 ID，请勿设置此参数。
android.enableSafeArea	在运行时控制 Android 安全区域内边距。嵌套在 android 键下，默认值为 true。

const view = await createFlowView(flow, {
  locale: 'en',
  customLayoutId: 'tablet_landscape',
  android: { enableSafeArea: true },
});

处理事件

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

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

其他所有事件处理器保持原有名称不变。有一个处理器的签名发生了变化：onAppeared 现在变为 (view) 而非 ()，其中 view 是一个 FlowEventView，描述了出现的视图——包括构建该视图所使用的本地化信息。现有处理器仍可正常工作，因为它们会忽略新增的参数。完整列表请参阅处理流程与付费墙事件。

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

• adapty.openWebUrl({ url, openIn }) 和 adapty.requestAppReview() 方法 — 这些方法支持默认的 onUrlPress 和 onRequestAppReview 处理程序，因此 URL 和应用评价请求可以原生开箱即用。只有在覆盖这些处理程序时才需要直接调用它们。
• 通过新的 onObserverPurchaseInitiated / onObserverRestoreInitiated 处理程序，在流程中支持 Observer 模式的购买处理。详见在 Observer 模式下展示流程。
• onAnalytics: (name, params) — 流程触发的分析事件，从用户打开每个页面时的页面浏览事件开始。详见追踪流程页面浏览。
• onRequestPermission: (permission, customArgs) — 为流程中的系统权限请求（如推送通知或相机访问）预留的接口。目前流程尚不会触发权限请求，因此无需实现此处理程序。

另外，4.1.1 还新增了一个 SDK 级别的事件（而非流程处理器）：'onPromotedPurchaseReceived'，通过 adapty.addListener 传递。若未注册监听器，SDK 将自行完成促销购买；注册监听器后，则由你的应用负责完成购买流程。详见 App Store 应用内推广购买。

重命名外部归因 API

从 SDK 4.1.1 版本开始，用于传递外部归因提供商（Adjust、AppsFlyer、Branch、Tenjin 或自定义提供商）归因数据的 API 已重命名，以与原生 SDK 保持一致。由于没有提供废弃别名，现有调用处在重命名之前将无法正常工作：

4.1.1 之前	4.1.1
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AttributionSource	AdaptyExternalAttributionProvider
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders

updateAttribution → updateExternalAttribution

该方法已重命名，其 source 选项更改为 provider。归因数据仍为普通对象：

- await adapty.updateAttribution({ attribution, source: 'adjust' });
+ await adapty.updateExternalAttribution({ attribution, provider: 'adjust' });

AttributionSource → AdaptyExternalAttributionProvider

提供者类型已重命名。它仍然是一个开放联合类型——预定义值为 'apple_search_ads'、'adjust'、'appsflyer'、'branch' 和 'tenjin'，同时也接受任意其他字符串，因此 Adapty 后续新增的提供者无需更新 SDK 即可使用：

- import type { AttributionSource } from '@adapty/capacitor';
+ import type { AdaptyExternalAttributionProvider } from '@adapty/capacitor';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

用户画像中列出已应用归因提供商的属性已重命名，其元素类型也随之更改：

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

读取该属性的代码需要更新——详见展示 Apple Ads 定向付费墙。

App Store 推广应用内购买

在 4.1.1 之前，在 App Store 产品页面推广的应用内购买会自动完成，Adapty 也会记录该交易，但你的应用无法拦截它。4.1.1 新增了这个钩子，因此这是一项新功能，而非迁移步骤：即使不添加任何代码，SDK 仍会自动为你完成推广购买。

仅编写代码以自行接管完成操作——例如先显示一个页面。为新的 'onPromotedPurchaseReceived' 事件注册一个监听器，并通过 adapty.makePromotedPurchase 完成购买。注册该监听器后，SDK 将停止自动为你完成促销购买。

默认行为变更

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

• 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 中已弃用，请改用 Flow & 付费墙编辑工具。目前该 API 仍可正常使用，但将在未来版本中移除，请尽快将您的用户引导迁移至 Flow & 付费墙编辑工具。

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