安装与配置 Flutter SDK

Adapty SDK 包含两个关键模块，可无缝集成到您的 Flutter 应用中：

Core Adapty：这是 Adapty 正常运行所必需的核心 SDK。
AdaptyUI：如果您使用 Adapty 付费墙编辑工具（一款无需编写代码即可轻松创建跨平台付费墙的工具），则需要此模块。

Tip

想看看 Adapty SDK 在移动应用中的真实集成示例？不妨看看我们的示例应用，其中演示了完整的配置流程，包括展示付费墙、发起购买以及其他基本功能。

要求

Adapty SDK 支持 iOS 13.0+，但需要 iOS 15.0+ 才能正常使用付费墙编辑工具创建的付费墙。

Adapty Flutter SDK 4.0 新增了 Flow Builder 支持，将最低要求提升至 iOS 15.0+、Xcode 26+ 以及 Flutter 3.32.0+（Dart 3.8.0+）。安装详情请参阅下方 Adapty SDK 4.0。

Info

Adapty Flutter SDK 4.0.4 及更高版本支持 Google Play Billing Library v8。

Adapty 与某个 Billing Library 版本兼容，并不意味着 Adapty 支持该版本中 Google 引入的所有功能。在使用新的 Google Play 计费功能之前，请参阅 Play Store 中的产品。

Info

安装 SDK 是 Adapty 配置流程的第 5 步。在应用内购买正常运行之前，您还需要将应用连接到各应用商店，然后在 Adapty 看板中创建产品、付费墙和版位。快速入门指南涵盖了所有必要步骤。

安装 Adapty SDK

Important

以下步骤安装的是最新稳定版 SDK（3.x）。如果你需要 v4（Flow Builder 所需，快速入门也使用该版本），请直接参考下方的 Adapty SDK 4.0: Swift Package Manager。

将 Adapty 添加到你的 pubspec.yaml 文件中：

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

运行以下命令安装依赖：
```
flutter pub get
```

在应用中导入 Adapty SDK：

import 'package:adapty_flutter/adapty_flutter.dart';

Adapty SDK 4.0：Swift Package Manager

将支持 Flow Builder 的 Adapty Flutter SDK 4.0 添加到您的 pubspec.yaml：

dependencies:
  adapty_flutter: 4.0.3

从 v4 开始，原生 iOS SDK 不再通过 CocoaPods 分发——插件仅通过 Swift Package Manager 拉取（CocoaPods 的 spec 仓库将于 2026 年 12 月变为只读）。如果您使用的是 Flutter 3.32–3.43，请先启用 Swift Package Manager 支持：

flutter config --enable-swift-package-manager

Flutter 3.44 及更高版本默认启用 Swift Package Manager，因此无需额外操作。

有关 v4 中的 API 变更，请参阅迁移指南。

激活 Adapty SDK 的 Adapty 模块

在您的应用代码中激活 Adapty SDK。

Note

Adapty SDK 在您的应用中只需激活一次。

获取您的 Public SDK Key：

打开 Adapty 看板，导航至 App settings → General。
在 Api keys 部分，复制 Public SDK Key（不是 Secret Key）。
将代码中的 "YOUR_PUBLIC_SDK_KEY" 替换为实际值。

或者，使用 Adapty CLI 以编程方式获取：

npm install -g adapty
adapty auth login
adapty apps list

或者，直接运行：

npx adapty auth login
adapty apps list

请确保使用 Public SDK key 初始化 Adapty，Secret key 仅用于服务端 API。
SDK keys 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的那个。


void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    _initializeAdapty();

    super.initState();
  }

  Future<void> _initializeAdapty() async {
    try {
      await Adapty().activate(
        configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
      );
    } catch (e) {
      // handle the error
    }
  }

  Widget build(BuildContext context) {
    return Text("Hello");
  }
}

Important

在调用任何其他 Adapty SDK 方法之前，请等待 activate 完成。完整调用顺序请参阅 Flutter SDK 调用顺序。

现在在你的应用中配置付费墙：

如果你使用 Adapty 付费墙编辑工具，请先激活 Adapty SDK 的 AdaptyUI 模块，然后按照付费墙编辑工具快速入门操作。
如果你自行构建付费墙 UI，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划使用付费墙编辑工具，并且已经安装了 AdaptyUI 模块，还需要激活 AdaptyUI：

Note

无论 AdaptyUI 是否已激活，与 AdaptyUI 相关的依赖项都会链接到你的应用中。

Important

在代码中，必须先激活 Adapty 核心模块，再激活 AdaptyUI。

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withActivateUI(true), // This automatically activates AdaptyUI
);

可选配置

日志记录

配置日志系统

Adapty 会记录错误及其他重要信息，帮助你了解运行状况。目前支持以下日志级别：

级别	描述
`AdaptyLogLevel.error`	仅记录错误日志
`AdaptyLogLevel.warn`	记录错误日志，以及 SDK 中不会导致严重错误但值得关注的消息。
`AdaptyLogLevel.info`	记录错误、警告及各类信息消息。默认值
`AdaptyLogLevel.verbose`	记录调试时可能有用的额外信息，例如函数调用、API 请求等。
`AdaptyLogLevel.debug`	记录调试信息。
您可以在配置 Adapty 之前在应用中设置日志级别：

// Set log level before activation. 
// 'verbose' is recommended for development and the first production release
await Adapty().setLogLevel(AdaptyLogLevel.verbose);

// Or set it during configuration
await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withLogLevel(AdaptyLogLevel.verbose),
);

数据政策

Adapty 不存储用户的个人数据，除非你明确发送，但你可以实施额外的数据安全策略以符合应用商店或国家/地区的规定。

在激活 Adapty 模块时，将 ipAddressCollectionDisabled 设置为 true 即可禁用用户 IP 地址的收集与共享。默认值为 false。使用此参数可以增强用户隐私保护、遵守区域性数据保护法规（如 GDPR 或 CCPA），或在您的应用不需要基于 IP 的功能时减少不必要的数据收集。

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withIpAddressCollectionDisabled(true),
);

激活 Adapty 模块时，将 appleIdfaCollectionDisabled（iOS）或 googleAdvertisingIdCollectionDisabled（Android）设置为 true 可禁用广告标识符的收集。默认值为 false。

如需遵守 App Store/Play Store 政策、避免触发应用追踪透明度提示，或者您的应用不需要基于广告 ID 的广告归因或分析功能，请使用此参数。

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleIdfaCollectionDisabled(true)      // iOS
    ..withGoogleAdvertisingIdCollectionDisabled(true), // Android
);

为 AdaptyUI 设置媒体缓存配置

该模块会随 Adapty SDK 自动激活。如果你不使用付费墙编辑工具，想要停用 AdaptyUI 模块，请在激活时传入 withActivateUI(false)。默认情况下，AdaptyUI 会缓存媒体文件（如图片和视频）以提升性能、减少网络流量。你可以通过提供自定义配置来调整缓存设置。

使用 withMediaCacheConfiguration 可覆盖默认缓存限制。该方法为可选项——如果不调用，将使用默认值（磁盘大小 100MB，内存数量不限）。但一旦创建了配置对象，其所有参数均为必填项。


final mediaCacheConfig = AdaptyUIMediaCacheConfiguration(
  memoryStorageTotalCostLimit: 200 * 1024 * 1024, // 200 MB
  memoryStorageCountLimit: 2147483647, // max int value
  diskStorageSizeLimit: 200 * 1024 * 1024, // 200 MB
);

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withMediaCacheConfiguration(mediaCacheConfig),
);

参数：

参数	是否必填	描述
memoryStorageTotalCostLimit	必填	内存缓存总大小，单位为字节。默认值为 100 MB。
memoryStorageCountLimit	必填	内存存储的条目数量限制。默认值为 int 最大值。
diskStorageSizeLimit	必填	磁盘文件大小限制，单位为字节。默认值为 100 MB。

启用本地访问等级（Android）

默认情况下，本地访问等级在 iOS 上已启用，在 Android 上处于禁用状态。如需在 Android 上也启用此功能，请将 withGoogleLocalAccessLevelAllowed 设置为 true：

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withGoogleLocalAccessLevelAllowed(true),
);

备份恢复时清除数据

将 appleClearDataOnBackup 设置为 true 后，SDK 会检测应用是否从 iCloud 备份中恢复，并删除所有本地存储的 SDK 数据，包括已缓存的用户画像信息、产品详情和付费墙。随后 SDK 将以全新状态重新初始化。默认值为 false。

Note

仅删除本地 SDK 缓存。Apple 的交易历史记录和 Adapty 服务器上的用户数据不受影响。

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleClearDataOnBackup(true) // default – false
);

故障排查

Android 备份规则（Auto Backup 配置）

部分 SDK（包括 Adapty）会附带自己的 Android Auto Backup 配置。如果您使用了多个定义备份规则的 SDK，Android 清单合并器可能会报错，错误信息中通常包含 android:fullBackupContent、android:dataExtractionRules 或 android:allowBackup。

常见错误提示：Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

Note

以下修改应在您的 Android 平台目录中进行（通常位于项目的 android/ 文件夹下）。

要解决此问题，您需要：

告知清单合并器使用您应用中的备份相关属性值。
创建备份规则文件，将 Adapty 的规则与其他 SDK 的规则合并。

1. 在清单文件中添加 `tools` 命名空间

在 AndroidManifest.xml 文件中，确保根标签 <manifest> 包含 tools：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. 在 `<application>` 中覆盖备份属性

在同一个 AndroidManifest.xml 文件中，更新 <application> 标签，使您的应用提供最终属性值，并通知清单合并器替换库中的属性值：

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

如果某个 SDK 也设置了 android:allowBackup，请将其一并加入 tools:replace：

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. 创建合并后的备份规则文件

在 Android 项目的 res/xml/ 目录中创建 XML 文件，将 Adapty 的规则与其他 SDK 的规则合并。由于 Android 在不同系统版本中使用不同的备份规则格式，同时创建两个文件可确保您的应用在所有支持的 Android 版本上都能正常运行。

Note

以下示例以 AppsFlyer 作为第三方 SDK 示例。请根据实际情况替换或添加您应用中所使用的其他 SDK 的规则。

适用于 Android 12 及更高版本（使用新的数据提取规则格式）：

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

适用于 Android 11 及更低版本（使用旧版完整备份内容格式）：

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

在 Android 上从其他应用返回后购买失败

如果启动购买流程的 Activity 使用了非默认的 launchMode，当用户从 Google Play、银行应用或浏览器返回时，Android 可能会错误地重建或复用该 Activity，导致购买结果丢失或被视为已取消。

为确保购买正常进行，请为启动购买流程的 Activity 仅使用 standard 或 singleTop 启动模式，避免使用其他任何模式。在您的 AndroidManifest.xml 中，确保启动购买流程的 Activity 设置为 standard 或 singleTop：

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

由 Podfile 中 SWIFT_VERSION 覆盖引起的 Swift 6 构建错误

在为 iOS 构建 Flutter 应用时，您可能会看到 Adapty pod 目标上出现 Swift 6 编译错误。常见症状包括：AdaptyUIBuilderLogic 中的 @Sendable 不匹配、Adapty 类型缺少 Sendable 一致性，或 actor 隔离错误。 The Adapty pods 声明 s.swift_version = '6.0' 并要求使用 Swift 6 进行构建。你自己的应用代码可以继续使用 Swift 5——只有 Adapty pod 目标（Adapty、AdaptyUI、AdaptyUIBuilder、AdaptyLogger、AdaptyPlugin）需要使用 Swift 6 构建。

最常见的原因是 ios/Podfile 中存在 post_install 钩子，它会为每个 pod 目标重写 SWIFT_VERSION：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

修复方法：将 Adapty pod targets 排除在覆盖范围之外：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

然后在 ios/ 目录下运行 pod install 并重新构建。

如需验证，请打开 ios/Pods/Pods.xcodeproj，选择 Adapty pod target → Build Settings → Swift Language Version，确认其值为 Swift 6。

安装与配置 Flutter SDK

要求

安装 Adapty SDK

Adapty SDK 4.0：Swift Package Manager

激活 Adapty SDK 的 Adapty 模块

激活 Adapty SDK 的 AdaptyUI 模块

可选配置

日志记录

配置日志系统

数据政策

禁用 IP 地址收集与共享

禁用广告 ID 的收集与共享

为 AdaptyUI 设置媒体缓存配置

启用本地访问等级（Android）

备份恢复时清除数据

故障排查

Android 备份规则（Auto Backup 配置）

1. 在清单文件中添加 tools 命名空间

2. 在 <application> 中覆盖备份属性

3. 创建合并后的备份规则文件

在 Android 上从其他应用返回后购买失败

由 Podfile 中 SWIFT_VERSION 覆盖引起的 Swift 6 构建错误

1. 在清单文件中添加 `tools` 命名空间

2. 在 `<application>` 中覆盖备份属性