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

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

• Core Adapty: Основной SDK, необходимый для работы Adapty в вашем приложении.
• AdaptyUI: Дополнительный модуль, необходимый при использовании Adapty Paywall Builder — удобного no-code инструмента для создания кроссплатформенных пейволов.

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

Требования

Хотя 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 (опционально — только если планируете использовать Paywall Builder)
   Note

   Примечание:

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

Активация модуля 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

• Убедитесь, что для инициализации 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)
  }
}

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

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

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

Если вы планируете использовать Paywall Builder и установили модуль 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 Review Guidelines или избежать появления запроса App Tracking Transparency, если 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

Включение Adapty Attribution

Если вы используете 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: 6.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"),
]