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

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

• Core Adapty: Этот основной SDK необходим для корректной работы Adapty в вашем приложении.
• AdaptyUI (io.adapty:adapty-kmp-ui): Этот модуль нужен, если вы используете Adapty Paywall Builder со слоем рендеринга 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" в коде на скопированный ключ.

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

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

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

Если вы планируете активировать модуль AdaptyUI для работы с Adapty 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 записывает ошибки и другую важную информацию, чтобы помочь вам разобраться в происходящем. Доступны следующие уровни:

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()

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

Правила резервного копирования 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" />