Установка и настройка Adapty Kotlin Multiplatform SDK

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

• Core Adapty: Этот основной SDK необходим для корректной работы Adapty в вашем приложении.
• AdaptyUI (io.adapty:adapty-kmp-ui): Этот модуль отображает флоу и пейволы старого билдера через слой рендеринга Compose Multiplatform (view.present()). Если ваш проект не использует Compose Multiplatform, вместо него можно использовать createNativePaywallView и createNativeOnboardingView из основного модуля.

Для полного обзора реализации вы также можете посмотреть видео:

Требования

Adapty Kotlin Multiplatform SDK совместим с Xcode 16.2 и более поздними версиями.

Установка Adapty SDK через 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 {
    sourceSets {
        commonMain {
            dependencies {
                implementation libs.adapty.kmp
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

// libs.versions.toml
[versions]
..
adapty-kmp    = "<the latest SDK version>"

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

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

dependencyResolutionManagement {
    ...
    repositories {
        ...
        google()
        mavenCentral()
    }
}

Активация Adapty SDK

Базовая настройка

Добавьте инициализацию как можно раньше — обычно в общем Kotlin-коде для обеих платформ.

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

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

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

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

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

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

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withActivateUI(true)           // true for activating the AdaptyUI module
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

Настройка Proguard (Android)

Перед выпуском приложения в продакшн вам может потребоваться добавить -keep class com.adapty.** { *; } в конфигурацию Proguard.

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

Логирование

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

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

Вы можете задать уровень логирования в вашем приложении до настройки Adapty:

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withLogLevel(AdaptyLogLevel.VERBOSE) // recommended for development
     .build()

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

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

При активации модуля Adapty установите ipAddressCollectionDisabled в значение true, чтобы отключить сбор и передачу IP-адресов пользователей. По умолчанию используется значение false.

Используйте этот параметр для усиления конфиденциальности пользователей, соблюдения региональных требований по защите данных (например, GDPR или CCPA), а также для сокращения избыточного сбора данных в случаях, когда функции на основе IP-адреса вашему приложению не нужны.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withIpAddressCollectionDisabled(true)
     .build()

Отключение сбора и передачи рекламных идентификаторов

При активации модуля Adapty установите appleIdfaCollectionDisabled (iOS) или googleAdvertisingIdCollectionDisabled (Android) в значение true, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — false.

Используйте этот параметр для соблюдения требований App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не использует рекламную атрибуцию или аналитику на основе рекламных идентификаторов.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withGoogleAdvertisingIdCollectionDisabled(true)        // Android only
     .withAppleIdfaCollectionDisabled(true)                  // iOS only
     .build()

Настройка конфигурации кэша медиа для AdaptyUI

По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения сетевого трафика. Вы можете настроить параметры кэша, передав собственную конфигурацию.

Используйте mediaCache, чтобы переопределить настройки кэша по умолчанию:

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)

По умолчанию локальные уровни доступа на Android отключены. Чтобы включить их, установите withLocalAccessLevelAllowed в true:

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withGoogleLocalAccessLevelAllowed(true)
    .build()

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

Когда withAppleClearDataOnBackup установлено в true, SDK определяет, что приложение было восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK, включая кэшированную информацию профиля, сведения о продуктах и пейволы. После этого SDK инициализируется с чистого состояния. Значение по умолчанию — false.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAppleClearDataOnBackup(true)
    .build()

Включение Adapty Attribution

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAdaptyAttributionEnabled(true)
    .build()

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

Правила резервного копирования Android (настройка Auto Backup)

Некоторые 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)

Чтобы решить эту проблему, нужно:

• Указать слиянию манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием.

• Создать файлы правил резервного копирования, которые объединяют правила Adapty с правилами других SDK.

1. Добавьте пространство имён tools в манифест

В файле AndroidManifest.xml убедитесь, что корневой тег <manifest> содержит tools:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Переопределите атрибуты резервного копирования в <application>

В том же файле AndroidManifest.xml обновите тег <application>, чтобы ваше приложение задавало финальные значения и указывало слиянию манифестов заменять значения библиотек:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Если какой-либо SDK также задаёт android:allowBackup, добавьте его в tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Создайте объединённые файлы правил резервного копирования

Создайте XML-файлы в директории res/xml/ вашего Android-проекта, объединив правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение.

Для Android 12 и выше (используется новый формат правил извлечения данных):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Для Android 11 и ниже (используется устаревший формат полного резервного копирования):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Покупки не проходят после возврата из другого приложения на Android

Если Activity, запускающая флоу покупки, использует нестандартный launchMode, Android может некорректно пересоздать или переиспользовать её, когда пользователь возвращается из Google Play, банковского приложения или браузера. Это может привести к потере результата покупки или к тому, что она будет считаться отменённой.

Чтобы покупки работали корректно, используйте только режимы standard или singleTop для Activity, запускающей флоу покупки, и избегайте любых других режимов.

В файле AndroidManifest.xml убедитесь, что Activity, запускающая флоу покупки, имеет значение standard или singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />