--- title: "Установка и настройка Adapty Kotlin Multiplatform SDK" description: "Установите и настройте Adapty SDK для приложений на Kotlin Multiplatform." --- Adapty SDK включает два ключевых модуля для бесшовной интеграции в ваше мобильное приложение: - **Core Adapty**: Основной SDK, необходимый для корректной работы Adapty в вашем приложении. - **AdaptyUI** (`io.adapty:adapty-kmp-ui`): Этот модуль нужен, если вы используете [Adapty Paywall Builder](adapty-paywall-builder) с отрисовкой через Compose Multiplatform (`view.present()`). Если ваш проект не использует Compose Multiplatform, вместо этого можно использовать [`createNativePaywallView`](kmp-present-paywalls#without-compose-multiplatform) и [`createNativeOnboardingView`](kmp-present-onboardings#without-compose-multiplatform) из основного модуля. :::tip Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наше [демо-приложение](https://github.com/adaptyteam/AdaptySDK-KMP/tree/main/example) — в нём показана полная настройка, включая отображение пейволов, совершение покупок и другую базовую функциональность. ::: Полное пошаговое руководство по реализации также доступно в видео: ## Требования \{#requirements\} Adapty Kotlin Multiplatform SDK совместим с Xcode 16.2 и более поздними версиями. :::info Adapty совместим с Google Play Billing Library до версии 8.x включительно. По умолчанию Adapty работает с Google Play Billing Library v.7.0.0, но если вы хотите принудительно использовать более позднюю версию, можно вручную [добавить зависимость](https://developer.android.com/google/play/billing/integrate#dependency). ::: --- no_index: true --- import Callout from '../../../components/Callout.astro'; Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. [Гайд по быстрому старту](quickstart) описывает все необходимые шаги. ## Установка Adapty SDK через Gradle \{#install-adapty-sdk-via-gradle\} Установка Adapty SDK через Gradle необходима как для Android, так и для iOS-приложений. Выберите способ настройки зависимостей: - Стандартный Gradle: добавьте зависимости в **module-level** `build.gradle` - Если в вашем проекте используются файлы `.gradle.kts`, добавьте зависимости в **module-level** `build.gradle.kts` - Если вы используете version catalogs, добавьте зависимости в файл `libs.versions.toml`, а затем сошлитесь на него в `build.gradle.kts` ```kotlin showLineNumbers kotlin { sourceSets { commonMain { dependencies { implementation libs.adapty.kmp } } } } ``` ```kotlin showLineNumbers kotlin { sourceSets { val commonMain by getting { dependencies { implementation(libs.adapty.kmp) } } } } ``` ```toml showLineNumbers // libs.versions.toml [versions] .. adapty-kmp = "" [libraries] .. adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" } // build.gradle.kts kotlin { sourceSets { val commonMain by getting { dependencies { implementation(libs.adapty.kmp) } } } } ``` :::note Если вы получаете ошибку, связанную с Maven, убедитесь, что в ваших Gradle-скриптах есть `mavenCentral()`.
Как это добавить Если в вашем `settings.gradle` нет `dependencyResolutionManagement`, добавьте следующее в корневой `build.gradle` в конец блока repositories: ```groovy showLineNumbers title="top-level build.gradle" allprojects { repositories { ... mavenCentral() } } ``` В противном случае добавьте следующее в `settings.gradle` в блок `repositories` раздела `dependencyResolutionManagement`: ```groovy showLineNumbers title="settings.gradle" dependencyResolutionManagement { ... repositories { ... google() mavenCentral() } } ```
::: ## Активация Adapty SDK \{#activate-adapty-sdk\} ### Базовая настройка \{#basic-setup\} Добавьте инициализацию как можно раньше — как правило, в общем Kotlin-коде для обеих платформ. :::note SDK достаточно активировать один раз. ::: ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .build() Adapty.activate(configuration = config) .onSuccess { Log.d("Adapty", "SDK initialised") } .onError { error -> Log.e("Adapty", "Adapty init error: ${error.message}") } ``` :::important Дождитесь завершения `activate` перед вызовом любых других методов Adapty SDK. Подробную последовательность см. в разделе [Порядок вызовов в Kotlin Multiplatform SDK](kmp-sdk-call-order). ::: Чтобы получить **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"` в коде на скопированный ключ. :::info - Используйте публичный SDK-ключ для инициализации Adapty — секретный ключ предназначен только для [серверного API](getting-started-with-server-side-api). - SDK-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, убедитесь, что выбрали правильный. ::: Теперь настройте пейволы в приложении: - Если вы используете [Adapty Paywall Builder](adapty-paywall-builder), сначала [активируйте модуль AdaptyUI](#activate-adaptyui-module-of-adapty-sdk) ниже, а затем следуйте [быстрому старту с Paywall Builder](kmp-quickstart-paywalls). - Если вы создаёте собственный UI для пейвола, см. [быстрый старт для кастомных пейволов](kmp-quickstart-manual). ## Активация модуля AdaptyUI в Adapty SDK \{#activate-adaptyui-module-of-adapty-sdk\} Если вы планируете использовать модуль **AdaptyUI** для работы с [Adapty Paywall Builder](kmp-present-paywalls), убедитесь, что в конфигурации указано `.withActivateUI(true)`. :::info важно В коде необходимо активировать основной модуль Adapty до активации AdaptyUI. ::: ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withActivateUI(true) // true для активации модуля AdaptyUI .build() Adapty.activate(configuration = config) .onSuccess { Log.d("Adapty", "SDK initialised") } .onError { error -> Log.e("Adapty", "Adapty init error: ${error.message}") } ``` ## Настройка Proguard (Android) \{#configure-proguard-android\} Перед выпуском приложения в продакшн вам может потребоваться добавить `-keep class com.adapty.** { *; }` в конфигурацию Proguard. ## Дополнительная настройка \{#optional-setup\} ### Логирование \{#logging\} #### Настройка системы логирования \{#set-up-the-logging-system\} Adapty записывает ошибки и другую важную информацию, чтобы вы понимали, что происходит. Доступны следующие уровни логирования: | Уровень | Описание | | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | | `AdaptyLogLevel.NONE` | Ничего не логируется. Значение по умолчанию | | `AdaptyLogLevel.ERROR` | Логируются только ошибки | | `AdaptyLogLevel.WARN` | Логируются ошибки и сообщения SDK, которые не вызывают критических ошибок, но заслуживают внимания | | `AdaptyLogLevel.INFO` | Логируются ошибки, предупреждения и различные информационные сообщения | | `AdaptyLogLevel.VERBOSE` | Логируется любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, запросы к API и т. д. | Вы можете задать уровень логирования в приложении до настройки Adapty: ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withLogLevel(AdaptyLogLevel.VERBOSE) // recommended for development .build() ``` ### Политика работы с данными \{#data-policies\} #### Отключить сбор и передачу IP-адресов \{#disable-ip-address-collection-and-sharing\} При активации модуля Adapty установите `ipAddressCollectionDisabled` в значение `true`, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — `false`. Используйте этот параметр для защиты конфиденциальности пользователей, соблюдения региональных норм защиты данных (например, GDPR или CCPA) или сокращения лишнего сбора данных, если функции на основе IP-адресов не нужны вашему приложению. ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withIpAddressCollectionDisabled(true) .build() ``` #### Отключение сбора и передачи рекламного идентификатора \{#disable-advertising-id-collection-and-sharing\} При активации модуля Adapty установите `appleIdfaCollectionDisabled` (iOS) или `googleAdvertisingIdCollectionDisabled` (Android) в значение true, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — false. Используйте этот параметр для соблюдения требований App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency или если ваше приложение не требует атрибуции рекламы или аналитики на основе рекламных идентификаторов. ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withGoogleAdvertisingIdCollectionDisabled(true) // Android only .withAppleIdfaCollectionDisabled(true) // iOS only .build() ``` #### Настройка конфигурации медиакеша для AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и сокращения сетевого трафика. Вы можете настроить параметры кэша, передав собственную конфигурацию. Используйте `mediaCache`, чтобы переопределить настройки кэша по умолчанию: ```kotlin val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withMediaCacheConfiguration( AdaptyConfig.MediaCacheConfiguration( memoryStorageTotalCostLimit = 200 * 1024 * 1024, // 200 MB memoryStorageCountLimit = Int.MAX_VALUE, diskStorageSizeLimit = 200 * 1024 * 1024 // 200 MB ) ) .build() ``` ### Включение локальных уровней доступа (Android) \{#enable-local-access-levels-android\} По умолчанию [локальные уровни доступа](local-access-levels) на Android отключены. Чтобы включить их, установите `withLocalAccessLevelAllowed` в `true`: ```kotlin title="Kotlin" showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withGoogleLocalAccessLevelAllowed(true) .build() ``` ### Очистка данных при восстановлении из резервной копии \{#clear-data-on-backup-restore\} Когда параметр `withAppleClearDataOnBackup` установлен в `true`, SDK определяет, что приложение восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK: кешированную информацию профиля, данные продуктов и пейволов. После этого SDK инициализируется с чистым состоянием. Значение по умолчанию — `false`. :::note Удаляется только локальный кеш SDK. История транзакций с Apple и данные пользователей на серверах Adapty остаются без изменений. ::: ```swift showLineNumbers val config = AdaptyConfig .Builder("PUBLIC_SDK_KEY") .withAppleClearDataOnBackup(true) .build() ``` ## Устранение неполадок \{#troubleshooting\} #### Правила резервного копирования Android (настройка Auto Backup) \{#android-backup-rules-auto-backup-configuration\} Некоторые SDK (включая Adapty) поставляются с собственной конфигурацией Android Auto Backup. Если вы используете несколько SDK, каждый из которых определяет правила резервного копирования, слияние манифестов Android может завершиться ошибкой, связанной с `android:fullBackupContent`, `android:dataExtractionRules` или `android:allowBackup`. Типичные симптомы ошибки: `Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)` :::note Эти изменения нужно вносить в директорию Android-платформы (обычно находится в папке `android/` вашего проекта). ::: Чтобы решить проблему, необходимо: - Указать механизму слияния манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием. - Создать файлы правил резервного копирования, объединяющие правила Adapty с правилами других SDK. #### 1. Добавьте пространство имён `tools` в манифест В файле `AndroidManifest.xml` убедитесь, что корневой тег `` включает tools: ```xml ... ``` #### 2. Переопределите атрибуты резервного копирования в `` В том же файле `AndroidManifest.xml` обновите тег ``, чтобы ваше приложение предоставляло итоговые значения и указывало механизму слияния манифестов заменять значения библиотек: ```xml ... ``` Если какой-либо SDK также задаёт `android:allowBackup`, включите его в `tools:replace`: ```xml tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules" ``` #### 3. Создайте объединённые файлы правил резервного копирования Создайте XML-файлы в директории `res/xml/` вашего Android-проекта, объединяющие правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение. :::note В примерах ниже в качестве стороннего SDK используется AppsFlyer. Замените или добавьте правила для других SDK, которые используются в вашем приложении. ::: **Для Android 12 и выше** (используется новый формат правил извлечения данных): ```xml title="sample_data_extraction_rules.xml" ``` **Для Android 11 и ниже** (используется устаревший формат полного резервного копирования): ```xml title="sample_backup_rules.xml" :::important В проекте Kotlin Multiplatform применяйте эти изменения в Android application module (том, который собирает APK/AAB), например `androidApp` или `app`: - Манифест: `androidApp/src/main/AndroidManifest.xml` - XML с правилами резервного копирования: `androidApp/src/main/res/xml/` ::: #### Покупки завершаются ошибкой после возврата из другого приложения на Android \{#purchases-fail-after-returning-from-another-app-in-android\} Если Activity, запускающая процесс покупки, использует нестандартный `launchMode`, Android может некорректно пересоздать или переиспользовать её при возврате пользователя из Google Play, банковского приложения или браузера. Это может привести к потере результата покупки или её обработке как отменённой. Чтобы покупки работали корректно, используйте только режимы `standard` или `singleTop` для Activity, запускающей процесс покупки, и избегайте любых других режимов. В файле `AndroidManifest.xml` убедитесь, что для Activity, запускающей процесс покупки, задан режим `standard` или `singleTop`: ```xml ```