---
title: "迁移 Adapty Flutter SDK 至 v4.3"
description: "迁移至 Adapty Flutter SDK v4.3：决定 Google Play 消息的显示方式、以 num 类型读取流程事件的数值参数，以及处理用户引导中的邮箱输入。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Adapty Flutter SDK 4.3 默认显示 Google Play 应用内消息，并更改了部分流程和用户引导事件数据的 Dart 类型。公共 API 未移除或重命名，因此无需修改代码即可针对 4.3 编译。若要保持原有行为不变，请参阅本指南逐一确认每处变更。

如果您仍在使用 4.0 版本，请先参阅[迁移到 v4.1](migration-to-flutter-sdk-41)，然后再按本指南操作。

## 快速参考 \{#quick-reference\}

| v4.1 | v4.3 |
|---|---|
| 不请求 Google Play 消息 | Android 上默认显示 Google Play 消息，包括在流程中 |
| 整数型流程事件参数在 Android 上以 `double` 形式传递 | 在两个平台上均以 `int` 形式传递 |
| 用户引导的邮箱字段以 `AdaptyOnboardingsTextInput` 形式传递 | 以 `AdaptyOnboardingsEmailInput` 形式传递 |
| 打印用户引导输入内容时会隐藏已输入的值 | 打印时显示已输入的值 |

## 安装 \{#installation\}

在 `pubspec.yaml` 中将 `adapty_flutter` 更新至 v4.3：

```yaml showLineNumbers title="pubspec.yaml"
dependencies:
  adapty_flutter: ^4.3.0
```

如果你的应用使用了 [Kids Mode](kids-mode-flutter)，请改为指定 `adapty_flutter_kids`：

```yaml showLineNumbers title="pubspec.yaml"
dependencies:
  adapty_flutter_kids: ^4.3.0
```

环境要求与 4.1 保持不变：**Flutter 3.32.0**（Dart 3.8.0）及 **iOS 15.0**。完整安装步骤请参阅[安装 Adapty SDK](sdk-installation-flutter)。

## Google Play 消息默认显示 \{#google-play-messages-are-shown-by-default\}

从 4.3 版本开始，SDK 会在每次 `activate` 后，于应用的 `Activity` 启动时请求 Google Play 应用内消息（例如付款失败通知）。这包括应用切回前台、流程或用户引导打开或关闭的时机，因此消息可能会覆盖在付费墙上方显示。

如果这对你的应用没有影响，无需做任何修改。若要自行控制消息的显示时机，请在 Android 上以手动处理模式激活 SDK，并在适合的时机调用 `showStoreMessages`：

```dart showLineNumbers title="main.dart"

final configuration = AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY');
if (Platform.isAndroid) {
  configuration.withStoreMessagesHandling(AdaptyStoreMessagesHandling.manual);
}
await Adapty().activate(configuration: configuration);
```

仅在 Android 上设置手动处理模式，iOS 保持不变：在 iOS 16 及更高版本中，手动处理模式同样会暂存 App Store 消息，直到应用调用 `showStoreMessages` 为止。完整 API 说明请参阅[控制 Store 消息](flutter-store-messages)。

:::warning
在手动模式下，商店不会自动显示消息。如果你的应用从未调用 `showStoreMessages`，用户将永远看不到付款失败的通知。
:::

## Android 上流程事件的数值参数类型变更为 `int` \{#numeric-flow-event-parameters-are-int-on-android\}

在 Android 上，流程分析事件的整数参数以前以 `double` 类型传递。从 4.3 版本起，这些参数改为以 `int` 类型传递，与 iOS 保持一致。此变更影响 `flowViewDidReceiveAnalyticEvent` 以及 `AdaptyUIFlowPlatformView` 的 `onDidReceiveAnalyticEvent` 回调，包括[流程输入](flutter-flow-input)事件的日期和时间值。

在 Android 上，将这些参数强制转换为 `double` 现在会抛出异常。请将数值参数读取为 `num`：

```diff showLineNumbers
- final timestamp = params['value'] as double;
+ final timestamp = params['value'] as num;
```

## 用户引导的邮件字段以 `AdaptyOnboardingsEmailInput` 形式传递 \{#onboarding-email-fields-arrive-as-adaptyon boardingsemailinput\}

从 4.3 版本起，用户引导中的邮件字段将通过 `onboardingViewOnStateUpdatedAction` 以及 `AdaptyUIOnboardingPlatformView` 的 `onStateUpdatedAction` 回调以 `AdaptyOnboardingsEmailInput` 形式传递。在此之前，它们以 `AdaptyOnboardingsTextInput` 形式传递。如果你的代码从文本 case 中读取邮件，请同时处理邮件 case：

```diff showLineNumbers
  switch (input) {
    case AdaptyOnboardingsTextInput(:final value):
      // text fields
      break;
+   case AdaptyOnboardingsEmailInput(:final value):
+     // email fields
+     break;
    case AdaptyOnboardingsNumberInput(:final value):
      // number fields
      break;
  }
```

数字字段现在以 `AdaptyOnboardingsNumberInput` 的形式传入。在 4.3 之前，这些字段的更新根本不会触发。详见[处理用户引导中的数据](flutter-onboarding-input)。

## 用户引导输入值会出现在打印输出中 \{#onboarding-input-values-appear-in-printed-output\}

打印 `AdaptyOnboardingsInputParams` 或 `AdaptyOnboardingsInput` 时，现在会显示用户输入的值。如果你的应用会记录这些对象的日志，请检查相关日志：其中现在可能包含用户输入的姓名、邮箱及其他个人信息。

## 4.3 版本新功能 \{#new-in-43\}

以下新增内容无需修改代码：

- **[控制商店消息](flutter-store-messages)**：选择 App Store 和 Google Play 消息的显示时机。
- **[预加载版位](flutter-optimize-paywall-fetching#preload-placements)**：`preloadFlows` 和 `preloadFlowsForDefaultAudience` 可预热流程缓存。
- **[释放已保留的视图](flutter-present-paywalls#dismiss-the-flow-or-paywall)**：`destroy()` 方法可释放通过 `dismiss(destroy: false)` 保留或从未展示的流程视图。
- **[12 个月承诺计划](set-up-12-month-commitment)**：`AdaptyProductSubscription.pricingTerms` 属性在 iOS 上描述该计划，访问等级会报告 `billingPlan` 和 `commitmentInfo`。
- **[观察者模式](report-transactions-observer-mode-flutter)**：`reportTransaction` 方法在 iOS 上接受可选的 `appleJwsTransaction` 参数。