安装并配置 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+

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

安装 Adapty SDK

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

输入代码仓库 URL：

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

选择版本（推荐选择最新稳定版本），然后点击 Add Package。
在 Choose Package Products 窗口中，选择所需的模块：
- Adapty（核心模块）
- AdaptyUI（可选 - 仅在您计划使用付费墙编辑工具时需要）
注意：
- 若要启用儿童模式，请选择 Adapty_KidsMode 代替 Adapty。
- 不要选择列表中的其他 Package——您不需要它们。
点击 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 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的密钥。

import SwiftUI
import Adapty

@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.

import Adapty

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 付费墙编辑工具，请先激活 AdaptyUI 模块，然后按照付费墙编辑工具快速入门操作。
如果您自行构建付费墙 UI，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

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

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

import SwiftUI
import Adapty
import AdaptyUI

@main
struct YourApp: App {
  init() {
    // ...ConfigurationBuilder steps
    
    // Activate Adapty SDK asynchronously
    Task {
      do {
        try await Adapty.activate(with: config)
        try await AdaptyUI.activate()
      } catch {
        // Handle error appropriately for your app
        print("Adapty activation failed: ", error)
      }
    }
    
    // main body...
  }
}

// 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.

import Adapty
import AdaptyUI

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

   let config = configurationBuilder.build()
   try await Adapty.activate(with: config)
   try await AdaptyUI.activate()
      } catch {
      // Handle error appropriately for your app
      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 的收集和共享。

当您的应用不需要 IDFA 时，可使用此参数遵守 App Store 审核指南或避免触发应用追踪透明度提示。默认值为 false。有关 IDFA 收集的更多详情，请参阅分析集成部分。

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

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

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

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

为 AdaptyUI 中的付费墙配置媒体缓存

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

import 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"),
]

安装并配置 iOS SDK

系统要求

安装 Adapty SDK

激活 Adapty SDK 的 Adapty 模块

激活 Adapty SDK 的 AdaptyUI 模块

可选配置

日志记录

配置日志系统

重定向日志系统消息

数据政策

禁用 IDFA 收集与共享

禁用 IP 收集与共享

为 AdaptyUI 中的付费墙配置媒体缓存

交易完成行为

备份恢复时清除数据

故障排除

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