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

• Core Adapty：这是 Adapty 正常运行所必需的核心 SDK。
• AdaptyUI：该模块用于渲染流程，以及旧版编辑工具付费墙。

系统要求

Adapty Flutter SDK 需要 iOS 15.0+、Xcode 26+ 以及 Flutter 3.32.0+（Dart 3.8.0+）。安装细节请参阅下方的 Swift Package Manager (iOS)。

依赖项

Adapty SDK 在 Android 上支持以下 Google Play Billing Library 版本：

Adapty SDK 版本	Billing Library 版本
4.0.4 及更高版本	v8
4.0.0–4.0.3	默认为 v7，若其他依赖项将其提升则为 v8

安装 Adapty SDK

我们始终建议安装最新版本的 SDK——它包含最新的稳定性修复和改进。

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

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

2. 运行以下命令安装依赖：

   flutter pub get

3. 在应用中导入 Adapty SDK：

   import 'package:adapty_flutter/adapty_flutter.dart';

Swift Package Manager（iOS）

该插件通过 Swift Package Manager 拉取原生 iOS SDK。如果你使用的是 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。

获取您的 Public SDK Key：

1. 打开 Adapty 看板，导航至 App settings → General。
2. 在 Api keys 部分，复制 Public SDK Key（不是 Secret Key）。
3. 将代码中的 "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");
  }
}

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

• 如果您使用 Flow & Paywall Builder，请先激活 AdaptyUI 模块（见下文），然后按照快速入门指南操作。
• 如果您自行构建付费墙 UI，请参见自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划使用 Flow & 付费墙编辑工具，并已安装 AdaptyUI 模块，还需要激活 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 不存储用户的个人数据，除非你明确发送，但你可以实施额外的数据安全策略以符合应用商店或国家/地区的规定。

禁用 IP 地址收集与共享

在激活 Adapty 模块时，将 ipAddressCollectionDisabled 设置为 true 即可禁用用户 IP 地址的收集与共享。默认值为 false。

使用此参数可以增强用户隐私保护、遵守区域性数据保护法规（如 GDPR 或 CCPA），或在您的应用不需要基于 IP 的功能时减少不必要的数据收集。

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

禁用广告 ID 的收集与共享

激活 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 自动激活。如果 Adapty 未能渲染您的页面，且您想停用 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。

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

启用 Adapty 归因

如果你使用 Adapty 归因，请在激活 SDK 时调用 withAdaptyAttributionEnabled(true)。默认值为 false：不传此参数时，SDK 不会注册安装事件，也不会向你的应用传递安装详情。在 4.1 以下版本的 SDK 中，Adapty 归因默认自动启用。

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

故障排查

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)

要解决此问题，您需要：

• 告知清单合并器使用您应用中的备份相关属性值。

• 创建备份规则文件，将 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 版本上都能正常运行。

适用于 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 隔离错误。

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 target 重写了 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 target 排除在覆盖范围之外：

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。