安装并配置 iOS SDK

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

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

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

系统要求

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

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

安装 Adapty SDK

Adapty SDK 通过 Swift Package Manager 安装。在 Xcode 中，依次点击 File -> Add Package Dependency…。不同版本的 Xcode 添加包依赖的步骤可能有所不同，如有需要请参阅 Xcode 官方文档。

1. 输入仓库 URL：

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

2. 选择版本（推荐使用最新稳定版），然后点击 Add Package。
3. 在 Choose Package Products 窗口中，选择所需模块：
   • Adapty（核心模块）
   • AdaptyUI（可选 - 仅在计划使用付费墙编辑工具时选择）
   注意：

   • 要启用 Kids 模式，请选择 Adapty_KidsMode 而非 Adapty。
   • 不要从列表中选择其他包 —— 你不需要它们。
4. 点击 Add Package 完成安装。
5. 验证安装： 在项目导航器中，你应该能在 Package Dependencies 下看到”Adapty”（以及”AdaptyUI”，如果已选择）。

激活 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" 替换为您的密钥。

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

激活 Adapty SDK 的 AdaptyUI 模块

如果你打算使用付费墙编辑工具并已安装 AdaptyUI 模块，还需要激活 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)
      }
    }

    // 主体内容...
  }
}

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

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

可选配置

日志记录

配置日志系统

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

 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 不会存储用户的个人数据。不过，您也可以实施额外的数据安全策略，以符合应用商店或所在国家/地区的相关规定。

禁用 IDFA 采集与共享

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

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

禁用 IP 收集与共享

在激活 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)

参数：

交易完成行为

默认情况下，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。

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