Установка и настройка iOS SDK

SDK Adapty включает два ключевых модуля для бесшовной интеграции в ваше мобильное приложение:

Core Adapty: Основной SDK, необходимый для работы Adapty в вашем приложении.
AdaptyUI: Опциональный модуль, отвечающий за отображение флоу, а также пейволов старого билдера.

Tip

Хотите посмотреть на реальный пример интеграции SDK Adapty в мобильное приложение? Ознакомьтесь с нашими примерами приложений — они демонстрируют полную настройку, включая отображение пейволов, совершение покупок и другие базовые функции.

Полное пошаговое руководство по реализации также доступно в видео:

Требования

Adapty iOS SDK требует iOS 15.0 или новее. Adapty SDK 4.0 и новее также требует Xcode 26 или новее для сборки, так как манифест Swift-пакета объявляет Swift tools 6.2.

Important

Adapty SDK 3.15.7+ необходим при сборке с Xcode 26.4 или новее.

Info

Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. Гайд по быстрому старту описывает все необходимые шаги.

Установка Adapty SDK

Мы всегда рекомендуем устанавливать последнюю доступную версию SDK — в ней содержатся актуальные исправления и улучшения.

Adapty SDK устанавливается через Swift Package Manager. В Xcode перейдите в File -> Add Package Dependency…. Обратите внимание, что шаги по добавлению зависимостей могут отличаться в разных версиях Xcode, поэтому при необходимости обращайтесь к документации Xcode.

Введите URL репозитория:

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

Выберите версию (рекомендуется последняя стабильная) и нажмите Add Package.
В окне Choose Package Products выберите нужные модули:
- Adapty (основной модуль)
- AdaptyUI (опционально — только если Adapty отрисовывает ваши экраны)
Note
Примечание:
- Чтобы включить режим «Дети» в SDK 3.x, выберите Adapty_KidsMode вместо Adapty. В SDK 4.0 и выше выбирайте стандартные модули — режим «Дети» включается через трейт пакета KidsMode.
- Не выбирайте другие пакеты из списка — они вам не понадобятся.
Нажмите Add Package, чтобы завершить установку.
Проверьте установку: в навигаторе проекта должны появиться «Adapty» (и «AdaptyUI», если он был выбран) в разделе Package Dependencies.

Активация модуля Adapty в SDK Adapty

Активируйте Adapty SDK в коде вашего приложения.

Note

Adapty SDK достаточно активировать один раз в приложении.

Чтобы получить Public SDK Key:

Откройте дашборд Adapty и перейдите в App settings → General.
В разделе Api keys скопируйте Public SDK Key (НЕ Secret Key).
Замените "YOUR_PUBLIC_SDK_KEY" в коде.

Или получите его программно с помощью Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Или напрямую:

npx adapty auth login
adapty apps list

Убедитесь, что для инициализации Adapty вы используете Public SDK key — Secret key предназначен только для серверного API.
SDK-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.


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

Important

Дождитесь завершения activate перед вызовом любых других методов Adapty SDK. Полная последовательность описана в порядке вызовов в iOS SDK.

Теперь настройте пейволы в приложении:

Если вы используете Flow & Paywall Builder, сначала активируйте модуль AdaptyUI ниже, затем следуйте быстрому старту.
Если вы строите собственный UI пейвола, смотрите быстрый старт для кастомных пейволов.

Активация модуля AdaptyUI в Adapty SDK

Если вы планируете использовать Flow & Paywall Builder и установили модуль AdaptyUI, его также необходимо активировать.

Important

В коде необходимо активировать основной модуль Adapty прежде, чем активировать 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)
   }
}

Tip

При желании, активируя AdaptyUI, вы можете переопределить настройки кеширования пейволов по умолчанию.

Дополнительная настройка

Логирование

Настройка системы логирования

Adapty записывает ошибки и другую важную информацию, чтобы вы понимали, что происходит. Доступны следующие уровни логирования:

Level	Description
`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 Review Guidelines или избежать появления запроса App Tracking Transparency, если IDFA не нужен вашему приложению. Значение по умолчанию — 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	required	Общий лимит стоимости хранилища в байтах.
memoryStorageCountLimit	required	Лимит количества элементов в памяти.
diskStorageSizeLimit	required	Лимит размера файлов на диске в байтах. 0 означает отсутствие лимита.

Поведение завершения транзакций

Info

Эта функция доступна начиная с версии 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.

Note

Удаляется только локальный кэш SDK. История транзакций в Apple и пользовательские данные на серверах Adapty остаются без изменений.

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

Включение Adapty Attribution

Info

Этот параметр доступен начиная с версии SDK 4.1.

Если вы используете Adapty Attribution, установите adaptyAttributionEnabled в true при активации SDK. Значение по умолчанию — false: без этого параметра SDK не регистрирует установки и не передаёт сведения об установке в ваше приложение. В версиях SDK ниже 4.1 Adapty Attribution включается автоматически.

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

Устранение неполадок

Ошибка конкурентности Swift 6 при использовании Tuist

При сборке с помощью Tuist могут возникать ошибки строгой конкурентности Swift 6. Типичные симптомы: несоответствие атрибута @Sendable в AdaptyUIBuilderLogic или аналогичные ошибки Sendability между модулями.

Это происходит потому, что Tuist генерирует проекты Xcode из пакетов SPM, но не сохраняет настройку swift-tools-version, которую объявляет SDK (6.0 в SDK 3.x, 6.2 начиная с SDK 4.0). В результате некоторые таргеты Adapty (Adapty, AdaptyUI, AdaptyUIBuilder) компилируются по правилам Swift 5, а другие — по правилам Swift 6, что вызывает несоответствия @Sendable между модулями.

Решение: Обновитесь до Adapty SDK 3.15.5 или новее — это устраняет проблему независимо от смешанных версий Swift.

Временное решение: Если обновление невозможно, явно задайте Swift 6 для всех трёх таргетов Adapty в конфигурации Tuist:

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

Установка и настройка iOS SDK

Требования

Установка Adapty SDK

Активация модуля Adapty в SDK Adapty

Активация модуля AdaptyUI в Adapty SDK

Дополнительная настройка

Логирование

Настройка системы логирования

Перенаправление сообщений системы логирования

Политики обработки данных

Отключение сбора и передачи IDFA

Отключение сбора и передачи IP-адресов

Конфигурация кэша медиа для пейволов в AdaptyUI

Поведение завершения транзакций

Очистка данных при восстановлении из резервной копии

Включение Adapty Attribution

Устранение неполадок

Ошибка конкурентности Swift 6 при использовании Tuist