安装与配置 iOS SDK

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

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

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

对于完整的实现演练，您也可以观看以下视频：

系统要求

虽然 SDK 核心模块在技术上支持 iOS 13.0+，但实际使用时需要 iOS 15.0+，原因如下：

所有 StoreKit 2 功能需要 iOS 15.0+
AdaptyUI 模块仅支持 iOS 15.0+

使用 Xcode 26.4 或更高版本构建时，需要 Adapty SDK 3.15.7+。

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

安装 Adapty SDK

在 Xcode 中，前往 File -> Add Package Dependency…。请注意，不同版本的 Xcode 添加包依赖的步骤可能有所不同，如有需要请参阅 Xcode 文档。

输入代码库 URL：

https://github.com/adaptyteam/AdaptySDK-iOS.git

选择版本（推荐使用最新稳定版），然后点击 Add Package。
在 Choose Package Products 窗口中，选择所需模块：
- Adapty（核心模块）
- AdaptyUI（可选 - 仅在计划使用付费墙编辑工具时选择）
注意：
- 若要启用儿童模式，请选择 Adapty_KidsMode 而非 Adapty。
- 不要从列表中选择其他任何包——你不会用到它们。
点击 Add Package 完成安装。
验证安装： 在项目导航栏中，你应该能在 Package Dependencies 下看到”Adapty”（以及”AdaptyUI”，如果已选择）。

CocoaPods 目前处于维护模式，官方已停止开发。我们建议切换到 Swift Package Manager。

将 Adapty 添加到你的 Podfile 中。根据需要选择以下模块：
1. Adapty 是必须安装的模块。
2. AdaptyUI 是可选模块，如果你计划使用 Adapty 付费墙编辑工具，则需要安装此模块。

   pod 'Adapty'
   pod 'AdaptyUI'  # optional module needed only for Paywall Builder

运行：
```
pod install
```

这将为你的应用创建一个 .xcworkspace 文件。之后的所有开发工作请使用该文件。

激活 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 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的密钥。


@main
struct YourApp: App {
  init() {
    // Configure Adapty SDK
    let configurationBuilder = AdaptyConfiguration
      .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // Get from Adapty dashboard

   Adapty.logLevel = .verbose // recommended for development and the first production release

    let config = configurationBuilder.build()

    // Activate Adapty SDK asynchronously
    Task {
      do {
        try await Adapty.activate(with: config)
      } catch {
        // Handle error appropriately for your app
        print("Adapty activation failed: ", error)
      }
    }

    var body: some Scene {
      WindowGroup {
        // Your content view
      }
    }
  }
}

// In your AppDelegate class:
// If you only use an AppDelegate, place the following code in the
// application(_:didFinishLaunchingWithOptions:) method.

// If you use a SceneDelegate, place the following code in the
// scene(_:willConnectTo:options:) method.


Task {
  do {
    let configurationBuilder = AdaptyConfiguration
      .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // Get from Adapty dashboard
      .with(logLevel: .verbose) // recommended for development and the first production release

    let config = configurationBuilder.build()
    try await Adapty.activate(with: config)
  } catch {
    // Handle error appropriately for your app
    print("Adapty activation failed: ", error)
  }
}

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

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

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

激活 Adapty SDK 的 AdaptyUI 模块

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

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


@main
struct YourApp: App {
  init() {
    // ...ConfigurationBuilder 步骤

    // 异步激活 Adapty SDK
    Task {
      do {
        try await Adapty.activate(with: config)
        try await AdaptyUI.activate()
      } catch {
        // 根据应用实际情况处理错误
        print("Adapty activation failed: ", error)
      }
    }

    // 主体内容...
  }
}

// 如果您只使用 AppDelegate，请将以下代码放在
// application(_:didFinishLaunchingWithOptions:) 方法中。

// 如果您使用 SceneDelegate，请将以下代码放在
// scene(_:willConnectTo:options:) 方法中。


Task {
   do {
      let configurationBuilder = AdaptyConfiguration
         .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") // 从 Adapty 看板获取
         .with(logLevel: .verbose) // 推荐在开发阶段使用

   let config = configurationBuilder.build()
   try await Adapty.activate(with: config)
   try await AdaptyUI.activate()
      } catch {
      // 根据您的应用情况进行适当的错误处理
      print("Adapty activation failed: ", error)
   }
}

可选步骤：激活 AdaptyUI 时，你可以覆盖付费墙的默认缓存设置。

可选配置

日志记录

配置日志系统

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

级别	描述
`error`	仅记录错误日志
`warn`	记录错误以及 SDK 中不会导致严重错误但值得关注的消息
`info`	记录错误、警告及各类信息消息
`verbose`	记录调试时可能有用的所有附加信息，例如函数调用、API 请求等

 let configurationBuilder = AdaptyConfiguration
         .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
         .with(logLevel: .verbose) // recommended for development

重定向日志系统消息

如果需要将 Adapty 的日志消息发送到你自己的系统或保存到文件，请使用 setLogHandler 方法并在其中实现自定义日志逻辑。该处理器会接收包含消息内容和严重级别的日志记录。

Adapty.setLogHandler { record in
    writeToLocalFile("Adapty \(record.level): \(record.message)")
}

数据政策

除非您主动发送，否则 Adapty 不会存储用户的个人数据。如有需要，您也可以实施额外的数据安全策略，以符合应用商店或所在地区的法规要求。

在激活 Adapty 模块时，将 idfaCollectionDisabled 设置为 true 即可禁用 IDFA 的收集与共享。使用此参数可遵守 App Store 审核指南，或在应用不需要 IDFA 时避免触发 App Tracking Transparency 弹窗。默认值为 false。有关 IDFA 收集的更多详情，请参阅分析集成部分。

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
        .with(idfaCollectionDisabled: true)

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

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

let configurationBuilder =
    AdaptyConfiguration
        .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
        .with(ipAddressCollectionDisabled: true)

付费墙的媒体缓存配置（AdaptyUI）

请注意，AdaptyUI 配置是可选的。你可以在不提供配置的情况下启用 AdaptyUI 模块。但如果你使用配置，则所有参数均为必填项。


// Configure AdaptyUI
        let adaptyUIConfiguration = AdaptyUI.Configuration(
            mediaCacheConfiguration: .init(
                memoryStorageTotalCostLimit: 100 * 1024 * 1024,
                memoryStorageCountLimit: .max,
                diskStorageSizeLimit: 100 * 1024 * 1024
            )
        )

        // Activate AdaptyUI
        AdaptyUI.activate(configuration: adaptyUIConfiguration)

参数：

参数	是否必填	描述
memoryStorageTotalCostLimit	必填	存储的总容量限制，单位为字节。
memoryStorageCountLimit	必填	内存存储的条目数量限制。
diskStorageSizeLimit	必填	存储的磁盘文件大小限制，单位为字节。0 表示不限制。

交易完成行为

此功能从 SDK 3.12.0 版本开始支持。

默认情况下，Adapty 在成功验证后会自动完成交易。但如果你需要进行高级交易验证（例如服务端收据验证、欺诈检测或自定义业务逻辑），可以将 SDK 配置为手动完成交易模式。

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(transactionsFinishBehavior: .manual) // .auto is the default

有关如何完成交易的更多详情，请参阅指南。

恢复备份时清除数据

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

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

let configurationBuilder = AdaptyConfiguration
    .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY")
    .with(clearDataOnBackup: true) // default – false

故障排查

使用 Tuist 时出现 Swift 6 并发错误

使用 Tuist 构建时，可能会遇到 Swift 6 严格并发编译错误。常见症状包括 AdaptyUIBuilderLogic 中出现 @Sendable 属性不匹配，或类似的跨模块 Sendability 错误。这是因为 Tuist 在从 SPM 包生成 Xcode 项目时，不会保留 swift-tools-version: 6.0 配置。因此，部分 Adapty 目标（Adapty、AdaptyUI、AdaptyUIBuilder）会以 Swift 5 规则编译，而其他目标使用 Swift 6，导致跨模块 @Sendable 不匹配。

修复方案：升级到 Adapty SDK 3.15.5 或更高版本，该版本无论 Swift 语言版本是否混用，均可解决此问题。

临时方案：如果暂时无法升级，请在 Tuist 配置中为以下三个 Adapty 目标显式指定 Swift 6：

targetSettings: [
  "Adapty": .init().swiftVersion("6"),
  "AdaptyUI": .init().swiftVersion("6"),
  "AdaptyUIBuilder": .init().swiftVersion("6"),
]

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

使用 CocoaPods 为 iOS 构建时，你可能会在 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）需要使用 Swift 6 构建。

最常见的原因是 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].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

然后运行 pod install 并重新构建。

验证方法：打开 Pods.xcodeproj，选择 Adapty pod target → Build Settings → Swift Language Version，确认版本为 Swift 6。

安装与配置 iOS SDK

系统要求

安装 Adapty SDK

激活 Adapty SDK 的 Adapty 模块

激活 Adapty SDK 的 AdaptyUI 模块

可选配置

日志记录

配置日志系统

重定向日志系统消息

数据政策

禁用 IDFA 收集与共享

禁用 IP 收集与共享

付费墙的媒体缓存配置（AdaptyUI）

交易完成行为

恢复备份时清除数据

故障排查

使用 Tuist 时出现 Swift 6 并发错误

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