将 Adapty Unity SDK 迁移至 v4.1

Adapty Unity SDK 4.1 是 4.x 系列的首个稳定版本——4.0 仅以 Beta 形式发布，因此如果你目前使用的是 3.x，请直接迁移至 4.1。本指南涵盖完整的迁移流程：4.0 中引入的流程功能，以及 4.1 新增的变更内容。

4.x 系列引入了流程（flows）并相应重命名了付费墙 API。新 API 支持流程，同时也兼容旧版编辑工具构建的付费墙——Adapty 看板无需进行任何配置变更。此外，4.1 还重命名了外部归因 API，将 Adapty Attribution 改为按需启用，新增了一个必须实现的监听器方法，并更改了备用文件格式。

Note

来自 4.0 beta？将固定的 beta 标签替换为 4.1.0 安装，之后只有四个部分适用：新监听器方法、重命名的外部归因 API、Adapty 归因默认禁用，以及备用文件。

快速参考

v3	v4.1
`Adapty.GetPaywall(placementId, locale, ...)`	`Adapty.GetFlow(placementId, ...)`
`Adapty.GetPaywallForDefaultAudience(placementId, locale, ...)`	`Adapty.GetFlowForDefaultAudience(placementId, ...)`
`Adapty.GetPaywallProducts(paywall, ...)`	`Adapty.GetPaywallProducts(flow, ...)`
`Adapty.LogShowPaywall(paywall, ...)`	`Adapty.LogShowFlow(flow, ...)`
`AdaptyPaywall`	`AdaptyFlow`
`AdaptyUI.CreatePaywallView(paywall, ...)`	`AdaptyUI.CreateFlowView(flow, ...)`
`AdaptyUICreatePaywallViewParameters`	`AdaptyUICreateFlowViewParameters`
`AdaptyUIPaywallView`	`AdaptyUIFlowView`
`AdaptyUI.PresentPaywallView(view, ...)` / `DismissPaywallView(view, ...)`	`AdaptyUI.PresentFlowView(view, ...)` / `DismissFlowView(view, ...)`
`Adapty.SetPaywallsEventsListener(listener)`	`Adapty.SetFlowsEventsListener(listener)`
`AdaptyPaywallsEventsListener`	`IAdaptyFlowsEventsListener`
`AdaptyEventListener`	`IAdaptyEventListener`，新增必需方法 `OnReceivePromotedPurchase`
`AdaptyOnboardingsEventsListener`	`IAdaptyOnboardingsEventsListener`
`PaywallViewDidPerformAction`、`PaywallViewDidAppear` 及其他 `PaywallView...` 回调	`FlowViewDidPerformAction`、`FlowViewDidAppear` 及其他 `FlowView...` 回调
`PaywallViewDidFailRendering`	`FlowViewDidReceiveError`
`Adapty.UpdateAttribution(data, source, ...)` 中 source 为 `string`	`Adapty.UpdateExternalAttribution(jsonString, provider, ...)` 中 provider 为 `AdaptyExternalAttributionProvider`
`AdaptyProfile.AppliedAttributionSources` 类型为 `IReadOnlyList<string>`	`AdaptyProfile.AppliedExternalAttributionProviders` 类型为 `IReadOnlyList<AdaptyExternalAttributionProvider>`
Adapty 归因默认自动启用	默认禁用——通过 `Builder.SetAdaptyAttributionEnabled(true)` 选择开启
适用于 3.x 的备用付费墙文件	新的备用文件格式——请重新下载文件
`Adapty.SetFallbackPaywalls(...)`（v3 中已废弃）	已移除——请使用 `Adapty.SetFallback(fileName, ...)`
`Builder.SetIDFACollectionDisabled(...)`（v3 中已废弃）	已移除——请使用 `Builder.SetAppleIDFACollectionDisabled(...)`
`paywall.Products`（`AdaptyProductReference` 列表）	已移除——请使用 `ProductIdentifiers` 或 `VendorProductIds`，或调用 `GetPaywallProducts(flow)` 获取完整产品信息
`AdaptyProductReference`	已作为公开类型移除——参见数据模型
`paywall.RemoteConfigString`	已移除——请使用 `flow.RemoteConfig?.Data`

AdaptyPaywallProduct 保持其名称不变——产品仍归属于某个流程，GetPaywallProducts 也保持其名称不变，现在接受一个 AdaptyFlow 参数。GetFlow 和 GetFlowForDefaultAudience 方法不再接受 locale 参数。购买与用户画像相关的 API（MakePurchase、RestorePurchases、GetProfile、Identify、UpdateProfile）保持不变。SetFallback 的签名不变，但它读取的文件需要重新下载——详见备用文件。用户引导方法仍可使用，但已被废弃——详见用户引导 API 废弃说明。部分默认行为已发生变化——详见默认行为变更。

安装

要通过 Unity Package Manager 安装 SDK 4.1，请在 Git URL 后追加版本标签：

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0

如果通过 Unity package 安装，请从 4.1.0 release 下载 adapty-unity-plugin-4.1.0.unitypackage。完整配置步骤请参阅安装 Adapty SDK。

4.x 版本带来了两项构建配置变更：

iOS 依赖项切换到 Swift Package Manager。 原生 Adapty iOS SDK 现以远程 Swift 包的形式声明，而非 CocoaPods pod。请将 External Dependency Manager 更新至 1.2.188 或更高版本——更早的版本不支持 Swift Package Manager 依赖项。CocoaPods 相关步骤（iOS Resolver -> Install Cocoapods、打开 Unity-iPhone.xcworkspace）不再适用。为 iOS 构建现在需要 Xcode 26 或更高版本，因为该 Swift 包使用 Swift tools 6.2 构建。
iOS 部署目标必须为 15.0 或更高版本。 Unity Editor 中新增了构建验证器，若目标版本低于此要求，iOS 构建将被阻止。

The underlying native Adapty SDKs are bumped to 4.x on both platforms and are resolved automatically — no other build changes are needed.

获取流程

GetPaywall → GetFlow

返回类型从 AdaptyPaywall 变更为 AdaptyFlow，同时移除了 locale 参数——当你渲染一个流程时，语言环境会自动解析；对于自定义付费墙，所有语言环境的配置都会通过 flow.RemoteConfigs 返回：

- Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
+ Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
      if (error != null) {
          // handle the error
          return;
      }
-     // use the paywall
+     // use the flow
  });

GetPaywallForDefaultAudience 已按相同方式重命名：

- Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => { /* ... */ });
+ Adapty.GetFlowForDefaultAudience("YOUR_PLACEMENT_ID", (flow, error) => { /* ... */ });

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts 保持名称不变，但现在接受 AdaptyFlow：

- Adapty.GetPaywallProducts(paywall, (products, error) => {
+ Adapty.GetPaywallProducts(flow, (products, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      // use the products
  });

数据模型

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

v3 `AdaptyPaywall` 属性	v4 `AdaptyFlow` 属性	操作
`RemoteConfig`（单个，可为空）	`RemoteConfigs`（列表）	一个流程携带每种已配置语言对应的一个远程配置。从 `flow.RemoteConfigs` 中读取与用户匹配的那个。`flow.RemoteConfig` 快捷方式返回第一个条目。
（新增）	`Paywalls`（`AdaptyFlowPaywall` 列表）	每个条目是流程中的一个付费墙变体，包含其自身的 `Name`、`VariationId` 和 `ProductIdentifiers`。Web 付费墙方法接受 `AdaptyFlowPaywall` — 参见 Web 付费墙方法。
`ProductIdentifiers`、`VendorProductIds`	保留	在 `AdaptyFlow` 上，这些属性汇总了所有付费墙变体的产品。每个变体也会暴露其自身的 `ProductIdentifiers` 和 `VendorProductIds`。获取产品时，继续调用 `GetPaywallProducts(flow)` 即可。
`HasViewConfiguration`	已移除	从代码中移除所有 `HasViewConfiguration` 检查 — `CreateFlowView` 会返回错误（参见展示流程）。
`Products`（`AdaptyProductReference` 列表）	已移除	`AdaptyProductReference` 不再公开，随之一并移除的还有其携带的 `PromotionalOfferId`、`WinBackOfferId` 和 `AndroidOfferId` 值。请使用 `ProductIdentifiers` — 一个包含 `VendorProductId` 和仅限 Android 的 `BasePlanId`（v3 的 `AndroidBasePlanId`）的 `AdaptyProductIdentifier` 列表 — 或在需要带有价格和优惠信息的完整 `AdaptyPaywallProduct` 对象时调用 `GetPaywallProducts(flow)`。
`RemoteConfigString`	已移除	直接从远程配置本身读取字符串：`flow.RemoteConfig?.Data`，或从 `flow.RemoteConfigs` 中找到匹配条目。
（新增）	`FlowVersionId`（可为空）	流程的版本标识符，或在不可用时为 `null`。

AdaptyPaywallProduct 新增了一个字段：FlowProductId，即产品在流程中的标识符，对于不属于任何流程的产品，该值为 null。

Web 付费墙方法

OpenWebPaywall 和 CreateWebPaywallUrl 名称保持不变，但 paywall 参数现在接受 AdaptyFlowPaywall——即 flow.Paywalls 中的某个变体。你也可以继续传入 AdaptyPaywallProduct：

- Adapty.OpenWebPaywall(paywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ var flowPaywall = flow.Paywalls.FirstOrDefault();
+ if (flowPaywall != null) {
+     Adapty.OpenWebPaywall(flowPaywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ }

追踪流程查看次数

LogShowPaywall → LogShowFlow

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

- Adapty.LogShowPaywall(paywall, (error) => { /* ... */ });
+ Adapty.LogShowFlow(flow, (error) => { /* ... */ });

与 v3 相同，当展示由 Adapty 渲染的流程或付费墙时，无需手动调用此方法——Adapty 会自动追踪这些浏览行为。

显示流程

CreatePaywallView → CreateFlowView

将工厂方法重命名，并传入 AdaptyFlow。返回的视图类型从 AdaptyUIPaywallView 更名为 AdaptyUIFlowView，但其方法（Present、Dismiss）保持不变，可选参数对象在新名称 AdaptyUICreateFlowViewParameters 下保留相同字段（LoadTimeout、PreloadProducts、CustomTags、CustomTimers、CustomAssets、ProductPurchaseParameters），并新增两个字段——Locale 和 EnableSafeAreaPaddings：

Note

CustomTimers 仍然存在，但它只影响旧版付费墙编辑工具的付费墙。流程的倒计时器按照 Flow & Paywall Builder 中设置的行为运行，因此流程会忽略此处传入的任何值。

- AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
+ AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      view.Present((error) => { /* handle the error */ });
  });

CreateFlowView 在未配置视图的情况下会返回错误，用于替代 v3 中的 HasViewConfiguration 检查：

- if (paywall.HasViewConfiguration) {
-     AdaptyUI.CreatePaywallView(paywall, null, (view, error) => { /* ... */ });
- }
+ AdaptyUI.CreateFlowView(flow, (view, error) => {
+     if (error != null) {
+         // the flow has no view configured, or view creation failed
+         return;
+     }
+     view.Present((error) => { /* handle the error */ });
+ });

Note

流程视图是一次性的：调用 Dismiss 后，视图将被销毁，如需再次展示该流程，请重新调用 CreateFlowView。

Android 安全区域内边距

AdaptyUICreateFlowViewParameters 新增了 EnableSafeAreaPaddings，用于在运行时控制 Android 安全区域内边距。该参数在 iOS 上会被忽略，默认值为 true：

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetEnableSafeAreaPaddings(false);

处理事件

监听器接口现在遵循 C# 的 I 前缀命名规范，且不保留任何旧版别名——在所有实现处，将 AdaptyEventListener 重命名为 IAdaptyEventListener，将 AdaptyOnboardingsEventsListener 重命名为 IAdaptyOnboardingsEventsListener。

流程事件监听器已从 AdaptyPaywallsEventsListener 重命名为 IAdaptyFlowsEventsListener，其注册方法从 SetPaywallsEventsListener 更改为 SetFlowsEventsListener，回调中的 PaywallView 前缀也更改为 FlowView。已有的处理器主体无需修改代码——只需重命名接口和方法即可：

- public class MyListener : MonoBehaviour, AdaptyPaywallsEventsListener {
-     public void PaywallViewDidFinishPurchase(
-         AdaptyUIPaywallView view,
+ public class MyListener : MonoBehaviour, IAdaptyFlowsEventsListener {
+     public void FlowViewDidFinishPurchase(
+         AdaptyUIFlowView view,
          AdaptyPaywallProduct product,
          AdaptyPurchaseResult purchasedResult
      ) {
          // custom logic after purchase
      }
      // ...
  }

- Adapty.SetPaywallsEventsListener(myListener);
+ Adapty.SetFlowsEventsListener(myListener);

一个回调已重命名：PaywallViewDidFailRendering 更名为 FlowViewDidReceiveError。它不仅会在之前的渲染错误时触发，还会在其他非购买类运行时错误时触发：

- public void PaywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) { }
+ public void FlowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) { }

完整回调列表请参阅处理流程与付费墙事件。

新增必要方法：OnReceivePromotedPurchase

从 SDK 4.1 版本起，IAdaptyEventListener 新增了一个方法，所有实现该接口的类在添加以下代码之前将无法通过编译：

public void OnReceivePromotedPurchase(AdaptyPromotedProduct product) {
    // The user tapped one of your in-app purchases on your App Store product page.
    // Complete the purchase through Adapty:
    Adapty.MakePromotedPurchase(product, (result, error) => { /* ... */ });
}

此方法适用于 App Store 推广的应用内购买，在 Android 上不会被调用。请勿将方法体留空：在 iOS 16.4 及更高版本中，SDK 会在此处传递购买请求并等待你完成处理，若方法体为空，用户已发起的购买将被丢弃。早期版本会自动完成此类购买。详见App Store 推广的应用内购买。

新 API

Adapty.SetObserverModeResolver(...) 配合 IAdaptyUIObserverModeResolver — 在 SDK 以观察者模式运行时，处理从流程发起的购买和恢复操作。此前该功能仅在原生 iOS 和 Android SDK 中可用。详见在观察者模式下展示流程。
Adapty.SetSystemRequestsHandler(...) 配合 IAdaptyUISystemRequestsHandler — 用于处理流程中的系统请求：操作系统权限提示（FlowViewDidAskPermission）和应用评价请求（FlowViewDidRequestAppReview）。当前流程尚不会触发这些请求，因此无需注册处理器。
AdaptyUICreateFlowViewParameters.Locale（通过 SetLocale 设置）— 使用特定的编辑工具本地化来渲染流程或付费墙，而非使用流程的默认语言。流程在视图创建时完成本地化，因此这是选择本地化的唯一时机，创建完成的视图会通过 view.Locale 报告其构建时所用的本地化。详见使用本地化和语言代码。
IAdaptyFlowsEventsListener 上新增的 FlowViewDidReceiveAnalyticEvent 回调，用于上报来自流程的分析事件，从用户打开的每个屏幕的页面浏览事件开始。详见追踪流程屏幕浏览。
AdaptyUI.OpenUrl(url, openIn, ...) 和 AdaptyUI.RequestAppReview(...) — open_url 操作和应用评价请求背后的原生处理逻辑。在 FlowViewDidPerformAction 中调用 OpenUrl 可保留默认的 URL 处理行为；RequestAppReview 支持默认的应用评价提示，但流程目前尚不会触发该功能。

重命名外部归因 API

从 SDK 4.1 版本开始，用于传入外部归因数据提供商（Adjust、AppsFlyer、Branch、Tenjin 或自定义提供商）数据的 API 已重命名，以与原生 SDK 保持一致，且提供商参数从字符串改为类型。由于没有废弃别名，现有调用处在更新之前将无法编译通过：

4.1 之前	4.1
`Adapty.UpdateAttribution(data, source, ...)`	`Adapty.UpdateExternalAttribution(jsonString, provider, ...)`
`source` 为 `string` 类型	`provider` 为 `AdaptyExternalAttributionProvider` 类型
`AdaptyProfile.AppliedAttributionSources` 为 `IReadOnlyList<string>`	`AdaptyProfile.AppliedExternalAttributionProviders` 为 `IReadOnlyList<AdaptyExternalAttributionProvider>`

仅重命名方法还不够——需要在同一次修改中替换 provider 参数：

- Adapty.UpdateAttribution(attributionJsonString, "adjust", (error) => { /* ... */ });
+ Adapty.UpdateExternalAttribution(attributionJsonString, AdaptyExternalAttributionProvider.Adjust, (error) => { /* ... */ });

AdaptyExternalAttributionProvider 携带后端识别提供商所用的标识符，内置六个共享实例：AppleAds（apple_search_ads）、Adjust、Appsflyer、Branch、Tenjin 和 Custom。对于本次 SDK 发布后 Adapty 新增的提供商，可通过其标识符构建实例——new AdaptyExternalAttributionProvider("your_provider")——数据将原样发送至后端。首尾空白字符会被自动去除。

归因数据以序列化 JSON 字符串的形式传入。如果你持有的是字典，请先将其序列化：

var attributionJsonString = Newtonsoft.Json.JsonConvert.SerializeObject(attribution);

在用户画像端，通过新类型读取已应用的提供商：

- if (profile.AppliedAttributionSources.Contains("apple_search_ads")) {
+ if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds)) {
      // Apple Ads attribution has been applied
  }

Adapty Attribution 默认禁用

Warning

如果你使用了 Adapty Attribution，并在未启用该功能的情况下升级到 SDK 4.1，将会发生静默故障——安装记录停止上报，且不会有任何警告提示。

在早期版本中，SDK 会自动为 Adapty Attribution 注册安装信息。从 SDK 4.1 版本起，该功能默认关闭：SDK 不再注册安装，OnInstallationDetailsSuccess 和 OnInstallationDetailsFail 监听回调不会触发，GetCurrentInstallationStatus 返回 NotAvailable 状态。

如果您使用 Adapty Attribution，请在激活 SDK 时启用它：

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

如果您不使用 Adapty Attribution，则无需进行任何更改。

备用文件

备用文件的格式在 SDK 4.1 中已发生变更。请从 Placements > Fallbacks 重新下载 iOS 和 Android 备用文件，并替换 Assets/StreamingAssets 中的旧文件，即使你之前已为早期版本下载过。

Warning

此步骤不会产生编译错误。如果跳过此步骤，SetFallback 将报告 DecodingFailed（adapty_code: 2006），且每个版位都将失去其备用付费墙。

默认行为变更

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

购买完成：在 v3 中，购买成功后视图会自动关闭。在 v4 中，购买或发生错误后，流程会保持打开状态，直到您主动关闭它 — SDK 不会应用任何默认行为。请在用户获得访问权限后，在 FlowViewDidFinishPurchase 中自行调用 view.Dismiss(...)。
Android 系统返回：系统返回按钮（或返回手势）会以 SystemBack 动作的形式传递给 FlowViewDidPerformAction，不再自动关闭流程 — 这与 iOS 保持一致，iOS 上的流程同样无法通过系统手势关闭。请为用户提供明确的退出方式（关闭按钮或 on_device_back 动作），或在处理该动作时自行关闭视图。
视图只能使用一次：调用 Dismiss 后，视图将被销毁。如需再次展示流程，请重新调用 CreateFlowView。
观察者模式事务：ReportTransaction 在成功时不再返回解码错误 — 在 v3 中，成功响应解析有误，导致成功的上报始终以错误结束。

用户引导 API 弃用

旧版用户引导 API 在 v4 中已被弃用，取而代之的是 Flow & 付费墙编辑工具。该 API 目前仍可正常使用，但将在未来版本中移除，请及时将您的用户引导迁移至 Flow & 付费墙编辑工具。

已弃用的符号：GetOnboarding、GetOnboardingForDefaultAudience、AdaptyUI.CreateOnboardingView、AdaptyUI.PresentOnboardingView、AdaptyUI.DismissOnboardingView 以及 Adapty.SetOnboardingsEventsListener。