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

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

• 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.
• Если вы создаёте собственный UI для пейвола, см. быстрый старт для кастомных пейволов.

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

Если вы планируете использовать модуль AdaptyUI для работы с Adapty Paywall Builder, убедитесь, что в конфигурации указано .withActivateUI(true).

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)

Перед выпуском приложения в продакшн вам может потребоваться добавить -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" />