安装并配置 Flutter SDK

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

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

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

系统要求

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

Adapty 兼容 Google Play Billing Library 最高至 8.x 版本。默认情况下，Adapty 使用 Google Play Billing Library v.7.0.0，但如果您希望强制使用更高版本，可以手动添加依赖。

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

安装 Adapty SDK

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

dependencies: 
  adapty_flutter: ^<the latest SDK version>

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

在您的应用中导入 Adapty SDK：

import 'package:adapty_flutter/adapty_flutter.dart';

激活 Adapty SDK 的 Adapty 模块

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

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

要获取您的 Public SDK Key：

前往 Adapty 控制台，导航至 App settings → General。
在 Api keys 部分，复制 Public SDK Key（不是 Secret Key）。
将代码中的 "YOUR_PUBLIC_SDK_KEY" 替换为您的密钥。

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

import 'package:adapty_flutter/adapty_flutter.dart';

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

现在在您的应用中设置付费墙：

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

激活 Adapty SDK 的 AdaptyUI 模块

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

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

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

平台特定配置

创建 Adapty-Info.plist 并将其添加到您的 iOS 项目中，然后添加以下配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>AdaptyPublicSdkKey</key>
    <string>YOUR_PUBLIC_SDK_KEY</string>
    <key>AdaptyObserverMode</key>
    <false/>
    <key>AdaptyAppleIdfaCollectionDisabled</key>
    <false/>
</dict>
</plist>

参数说明：

参数	是否必填	描述
AdaptyPublicSdkKey	必填	您可以在 Adapty 应用设置的 Public SDK key 字段中找到此密钥：App settings -> General 标签页 -> API keys 子章节
AdaptyObserverMode	可选	控制观察者模式的布尔值。如果您自行处理购买和订阅状态，并使用 Adapty 发送订阅事件和分析数据，请开启此选项。默认值为 `false`。🚧 在观察者模式下运行时，Adapty SDK 不会关闭任何交易，请确保您自己处理。
AdaptyAppleIdfaCollectionDisabled	可选	允许您为 iOS 应用禁用 Apple IDFA 收集的布尔参数。默认值为 `false`。更多详情，请参阅分析集成章节。

将以下配置添加到您的 AndroidManifest.xml：

<application ...>
    
    
    <meta-data
        android:name="AdaptyPublicSdkKey"
        android:value="YOUR_PUBLIC_SDK_KEY" />
    <meta-data
        android:name="AdaptyObserverMode"
        android:value="false" />
    <meta-data
        android:name="AdaptyGoogleAdvertisingIdCollectionDisabled"
        android:value="false" />
</application>

参数说明：

参数	是否必填	描述
AdaptyPublicSdkKey	必填	您可以在 Adapty 应用设置的 Public SDK key 字段中找到此密钥：App settings -> General 标签页 -> API keys 子章节。请确保在 Adapty 初始化时使用 Public SDK key，Secret key 仅应用于服务端 API。
AdaptyObserverMode	可选	控制观察者模式的布尔值。如果您自行处理购买和订阅状态，并使用 Adapty 发送订阅事件和分析数据，请开启此选项。默认值为 `false`。🚧 在观察者模式下运行时，Adapty SDK 不会关闭任何交易，请确保您自己处理。
AdaptyGoogleAdvertisingIdCollectionDisabled	可选	允许您为应用禁用 Google 广告 ID 收集的布尔参数。默认值为 `false`。更多详情，请参阅分析集成章节。

可选配置

日志记录

设置日志记录系统

Adapty 会记录错误和其他重要信息，帮助您了解运行情况。以下是可用的日志级别：

级别	描述
`AdaptyLogLevel.none`	不记录任何内容。默认值
`AdaptyLogLevel.error`	仅记录错误
`AdaptyLogLevel.warn`	记录错误以及 SDK 中不会导致严重错误但值得关注的消息
`AdaptyLogLevel.info`	记录错误、警告和各种信息消息
`AdaptyLogLevel.verbose`	记录调试期间可能有用的任何附加信息，例如函数调用、API 查询等

您可以在配置 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 政策、避免触发 App 追踪透明度提示，或在您的应用不需要基于广告 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，内存数量不限）。但如果您使用了该配置，所有参数都必须包含在内。

import 'package:adapty_flutter/adapty_flutter.dart';

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	可选	内存存储的条目数量限制。默认值为最大整数值。
diskStorageSizeLimit	可选	磁盘上的文件大小限制（字节）。默认值为 100 MB。

启用本地访问等级（Android）

默认情况下，本地访问等级在 iOS 上已启用，在 Android 上已禁用。要在 Android 上同样启用，请将 withGoogleLocalAccessLevelAllowed 设置为 true：

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

备份恢复时清除数据

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

仅删除本地 SDK 缓存。Apple 的交易记录和 Adapty 服务器上的用户数据保持不变。

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

故障排查

Android 备份规则（自动备份配置）

部分 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)

这些更改应在您的 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 版本上的兼容性。

以下示例使用 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" />

安装并配置 Flutter SDK

系统要求

安装 Adapty SDK

激活 Adapty SDK 的 Adapty 模块

激活 Adapty SDK 的 AdaptyUI 模块

平台特定配置

可选配置

日志记录

设置日志记录系统

数据策略

禁用 IP 地址收集和共享

禁用广告 ID 收集和共享

为 AdaptyUI 设置媒体缓存配置

启用本地访问等级（Android）

备份恢复时清除数据

故障排查

Android 备份规则（自动备份配置）

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

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

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

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

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

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