安装与配置 iOS SDK

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

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

如需完整的实现演示，也可以观看以下视频：

系统要求

Adapty iOS SDK 需要 iOS 15.0 或更高版本。Adapty SDK 4.0 及更高版本还需要 Xcode 26 或更高版本才能构建，因为其 Swift 包清单声明了 Swift tools 6.2。

安装 Adapty SDK

我们始终建议安装最新版本的 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（可选 - 仅在由 Adapty 渲染您的页面时才需要）
   Note

   注意：

   • 若要在 SDK 3.x 中启用儿童模式，请选择 Adapty_KidsMode 而非 Adapty。在 SDK 4.0 及更高版本中，选择常规模块即可——儿童模式通过 KidsMode 包特性来启用。
   • 不要从列表中选择其他任何包——您不需要它们。
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" 替换为实际值。

或者，使用 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 对每个应用都是唯一的，如果您有多个应用，请确保选择正确的那个。

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

接下来在应用中配置付费墙：

• 如果你使用 Flow & 付费墙编辑工具，请先 激活 AdaptyUI 模块，然后按照快速入门指南操作。
• 如果你自行构建付费墙界面，请参阅自定义付费墙快速入门。

激活 Adapty SDK 的 AdaptyUI 模块

如果你计划使用流程与付费墙编辑工具，并且已经安装了 AdaptyUI 模块，还需要激活 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.


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 时避免触发 App Tracking Transparency 提示。默认值为 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

启用 Adapty 归因

如果您使用 Adapty 归因，请在激活 SDK 时将 adaptyAttributionEnabled 设置为 true。默认值为 false：不传此参数时，SDK 不会注册安装事件，也不会向您的应用传递安装详情。在低于 4.1 的 SDK 版本中，Adapty 归因会自动启用。

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

故障排查

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

使用 Tuist 构建时，可能会遇到 Swift 6 严格并发编译错误。常见症状包括 AdaptyUIBuilderLogic 中的 @Sendable 属性不匹配，或类似的跨模块 Sendability 错误。

这是因为 Tuist 从 SPM 包生成 Xcode 项目时，不会保留 SDK 声明的 swift-tools-version 设置（SDK 3.x 为 6.0，SDK 4.0 起为 6.2）。因此，部分 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"),
]