--- title: "Установка и настройка iOS SDK" description: "Пошаговый гайд по установке Adapty SDK на iOS для приложений с подписками." --- Adapty SDK включает два ключевых модуля для бесшовной интеграции в ваше мобильное приложение: - **Core Adapty**: основной SDK, без которого Adapty не будет работать в вашем приложении. - **AdaptyUI**: опциональный модуль, нужный при использовании [Adapty Paywall Builder](adapty-paywall-builder) — удобного no-code инструмента для создания кросс-платформенных пейволов. :::tip Хотите посмотреть, как Adapty SDK интегрируется в реальное приложение? Загляните в наши [примеры приложений](https://github.com/adaptyteam/AdaptySDK-iOS/tree/master/Examples): там показана полная настройка, включая отображение пейволов, совершение покупок и другие базовые функции. ::: Для полного ознакомления с реализацией можете также посмотреть видео:
## Требования \{#requirements\} Хотя SDK технически поддерживает iOS 13.0+ для основного модуля, на практике требуется iOS 15.0+, поскольку: - Все возможности StoreKit 2 требуют iOS 15.0+ - Модуль AdaptyUI работает только на iOS 15.0+ --- no_index: true --- import Callout from '../../../components/Callout.astro'; Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. [Гайд по быстрому старту](quickstart) описывает все необходимые шаги. ## Установка Adapty SDK \{#install-adapty-sdk\} [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-iOS.svg?style=flat&logo=apple)](https://github.com/adaptyteam/AdaptySDK-iOS/releases) В 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](kids-mode) выберите **Adapty_KidsMode** вместо **Adapty**. - Не выбирайте другие пакеты из списка — они вам не понадобятся. ::: 4. Нажмите **Add Package** для завершения установки. 5. **Проверьте установку:** в навигаторе проекта должны появиться «Adapty» (и «AdaptyUI», если был выбран) в разделе **Package Dependencies**. :::info CocoaPods перешёл в режим поддержки, и его разработка официально прекращена. Рекомендуем перейти на [Swift Package Manager](sdk-installation-ios#install-adapty-sdk). ::: 1. Добавьте Adapty в ваш `Podfile`. Выберите нужные модули: 1. **Adapty** — обязательный модуль. 2. **AdaptyUI** — опциональный модуль, нужный при планировании использования [Adapty Paywall Builder](adapty-paywall-builder). ```shell showLineNumbers title="Podfile" pod 'Adapty' pod 'AdaptyUI' # optional module needed only for Paywall Builder ``` 2. Выполните: ```sh showLineNumbers title="Shell" pod install ``` В результате будет создан файл `.xcworkspace` для вашего приложения. Используйте его для всей дальнейшей разработки. ## Активация модуля Adapty в Adapty SDK \{#activate-adapty-module-of-adapty-sdk\} Активируйте Adapty SDK в коде вашего приложения. :::note Adapty SDK нужно активировать только один раз в приложении. ::: Чтобы получить **Public SDK Key**: 1. Откройте дашборд Adapty и перейдите в [**App settings → General**](https://app.adapty.io/settings/general). 2. В разделе **Api keys** скопируйте **Public SDK Key** (не Secret Key). 3. Замените `"YOUR_PUBLIC_SDK_KEY"` в коде на скопированный ключ. :::important - Используйте **Public SDK key** для инициализации Adapty. **Secret key** предназначен только для [серверного API](getting-started-with-server-side-api). - **SDK keys** уникальны для каждого приложения, поэтому при наличии нескольких приложений убедитесь, что выбрали правильный ключ. ::: ```swift showLineNumbers @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 } } } } ``` ```swift showLineNumbers // 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](adapty-paywall-builder), сначала [активируйте модуль AdaptyUI](#activate-adaptyui-module-of-adapty-sdk) ниже, затем следуйте [быстрому старту с Paywall Builder](ios-quickstart-paywalls). - Если вы создаёте собственный UI для пейвола, см. [быстрый старт для кастомных пейволов](ios-quickstart-manual). ## Активация модуля AdaptyUI в Adapty SDK \{#activate-adaptyui-module-of-adapty-sdk\} Если вы планируете использовать [Paywall Builder](adapty-paywall-builder) и [установили модуль AdaptyUI](sdk-installation-ios#install-adapty-sdk), вам также нужно активировать AdaptyUI. :::important В коде необходимо активировать основной модуль Adapty до активации AdaptyUI. ::: ```swift showLineNumbers title="Swift" @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... } } ``` ```swift showLineNumbers title="UIKit" // 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, вы можете [переопределить настройки кеширования по умолчанию для пейволов](#set-up-media-cache-configuration-for-adaptyui). ::: ## Дополнительная настройка \{#optional-setup\} ### Логирование \{#logging\} #### Настройка системы логирования \{#set-up-the-logging-system\} Adapty логирует ошибки и другую важную информацию, чтобы помочь вам разобраться в происходящем. Доступны следующие уровни: | Уровень | Описание | | ---------- | ------------------------------------------------------------ | | `error` | Логируются только ошибки | | `warn` | Логируются ошибки и сообщения от SDK, которые не вызывают критических ошибок, но заслуживают внимания | | `info` | Логируются ошибки, предупреждения и различные информационные сообщения | | `verbose` | Логируется любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, запросы к API и т.д. | ```swift showLineNumbers let configurationBuilder = AdaptyConfiguration .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") .with(logLevel: .verbose) // recommended for development ``` #### Перенаправление сообщений системы логирования \{#redirect-the-logging-system-messages\} Если вам нужно отправлять лог-сообщения Adapty в вашу систему или сохранять их в файл, используйте метод `setLogHandler` и реализуйте в нём собственную логику логирования. Этот обработчик получает записи логов с содержимым сообщения и уровнем серьёзности. ```swift showLineNumbers title="Swift" Adapty.setLogHandler { record in writeToLocalFile("Adapty \(record.level): \(record.message)") } ``` ### Политики обработки данных \{#data-policies\} Adapty не хранит персональные данные ваших пользователей, если вы явно их не передаёте, однако вы можете настроить дополнительные политики безопасности данных для соответствия требованиям сторов или законодательства отдельных стран. #### Отключение сбора и передачи IDFA \{#disable-idfa-collection-and-sharing\} При активации модуля Adapty установите `idfaCollectionDisabled` в `true`, чтобы отключить сбор и передачу IDFA. Используйте этот параметр для соответствия правилам App Store Review Guidelines или чтобы избежать показа запроса App Tracking Transparency, когда IDFA не нужен вашему приложению. Значение по умолчанию: `false`. Подробнее о сборе IDFA — в разделе [Интеграция аналитики](analytics-integration#disable-collection-of-advertising-identifiers). ```swift showLineNumbers let configurationBuilder = AdaptyConfiguration .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") .with(idfaCollectionDisabled: true) ``` #### Отключение сбора и передачи IP-адреса \{#disable-ip-collection-and-sharing\} При активации модуля Adapty установите `ipAddressCollectionDisabled` в `true`, чтобы отключить сбор и передачу IP-адреса пользователя. Значение по умолчанию: `false`. Используйте этот параметр для повышения конфиденциальности пользователей, соответствия региональным требованиям по защите данных (например, GDPR или CCPA) или для сокращения излишнего сбора данных, когда функции на основе IP не нужны вашему приложению. ```swift showLineNumbers let configurationBuilder = AdaptyConfiguration .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") .with(ipAddressCollectionDisabled: true) ``` #### Настройка кеширования медиа для пейволов в AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} Конфигурация AdaptyUI является опциональной. Вы можете активировать модуль AdaptyUI без конфига. Однако если вы используете конфиг, все параметры обязательны. ```swift showLineNumbers title="Swift" // 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 означает отсутствие ограничений. | ### Поведение при завершении транзакций \{#transaction-finishing-behavior\} :::info Эта функция доступна начиная с версии SDK 3.12.0. ::: По умолчанию Adapty автоматически завершает транзакции после успешной валидации. Однако если вам нужна расширенная валидация транзакций (например, серверная проверка чека, обнаружение мошенничества или собственная бизнес-логика), вы можете настроить SDK на ручное завершение транзакций. ```swift showLineNumbers title="Swift" let configurationBuilder = AdaptyConfiguration .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") .with(transactionsFinishBehavior: .manual) // .auto is the default ``` Подробнее о завершении транзакций — в [гайде](ios-transaction-management). ### Очистка данных при восстановлении из резервной копии \{#clear-data-on-backup-restore\} Когда `clearDataOnBackup` установлен в `true`, SDK обнаруживает восстановление приложения из резервной копии iCloud и удаляет все локально сохранённые данные SDK, включая кешированную информацию профиля, данные продуктов и пейволы. После этого SDK инициализируется с чистого состояния. Значение по умолчанию: `false`. :::note Удаляется только локальный кеш SDK. История транзакций с Apple и данные пользователя на серверах Adapty остаются без изменений. ::: ```swift showLineNumbers let configurationBuilder = AdaptyConfiguration .builder(withAPIKey: "YOUR_PUBLIC_SDK_KEY") .with(clearDataOnBackup: true) // default – false ``` ## Устранение неполадок \{#troubleshooting\} #### Ошибка конкурентности Swift 6 при использовании Tuist \{#swift-6-concurrency-error-with-tuist\} При сборке с помощью [Tuist](https://tuist.dev/) могут возникать ошибки строгой проверки конкурентности 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: ```swift showLineNumbers targetSettings: [ "Adapty": .init().swiftVersion("6"), "AdaptyUI": .init().swiftVersion("6"), "AdaptyUIBuilder": .init().swiftVersion("6"), ] ``` #### Ошибки сборки Swift 6 из-за переопределения SWIFT_VERSION в Podfile \{#swift-6-build-errors-caused-by-podfile-swift_version-override\} При сборке для iOS с использованием [CocoaPods](sdk-installation-ios#install-adapty-sdk) могут возникать ошибки компиляции Swift 6 в pod-таргетах Adapty. Типичные симптомы: несоответствия `@Sendable` в `AdaptyUIBuilderLogic`, отсутствие соответствия `Sendable` у типов Adapty или ошибки изоляции акторов. В подах Adapty объявлено `s.swift_version = '6.0'`, и для их сборки требуется Swift 6. Код вашего приложения может оставаться на Swift 5 — Swift 6 нужен только для целей подов Adapty (`Adapty`, `AdaptyUI`, `AdaptyUIBuilder`, `AdaptyLogger`). Самая распространённая причина проблемы — хук `post_install` в `Podfile`, который перезаписывает `SWIFT_VERSION` для всех целей подов: ```ruby showLineNumbers title="Podfile" post_install do |installer| installer.pods_project.targets.each do |target| target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.9' end end end ``` **Исправление**: исключите pod-таргеты Adapty из переопределения: ```ruby showLineNumbers title="Podfile" post_install do |installer| installer.pods_project.targets.each do |target| next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger].include?(target.name) target.build_configurations.each do |config| config.build_settings['SWIFT_VERSION'] = '5.9' end end end ``` Затем выполните `pod install` и пересоберите проект. Для проверки откройте `Pods.xcodeproj`, выберите pod-таргет `Adapty` → **Build Settings** → **Swift Language Version**. Должно быть указано **Swift 6**.