Установка и настройка Android SDK

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

• Core Adapty: основной SDK, без которого Adapty не будет работать.
• AdaptyUI: модуль, необходимый при использовании Adapty Paywall Builder — удобного no-code инструмента для создания кросс-платформенных пейволов. AdaptyUI активируется автоматически вместе с основным модулем.

Требования

Минимальная версия SDK: minSdkVersion 21

Установите Adapty SDK

Выберите способ настройки зависимостей:

• Стандартный Gradle: добавьте зависимости в build.gradle на уровне модуля
• Если в проекте используются файлы .gradle.kts, добавьте зависимости в build.gradle.kts на уровне модуля
• Если вы используете каталоги версий, добавьте зависимости в файл libs.versions.toml, а затем сошлитесь на него в build.gradle.kts

dependencies {
    ...
    implementation platform('io.adapty:adapty-bom:<the latest SDK version>')
    implementation 'io.adapty:android-sdk'

    // Only add this line if you plan to use Paywall Builder
    implementation 'io.adapty:android-ui'
}

dependencies {
    ...
    implementation(platform("io.adapty:adapty-bom:<the latest SDK version>"))
    implementation("io.adapty:android-sdk")

    // Добавьте эту строку только если планируете использовать Paywall Builder:
    implementation("io.adapty:android-ui")
}

//libs.versions.toml

[versions]
..
adaptyBom = "<the latest SDK version>"

[libraries]
..
adapty-bom = { module = "io.adapty:adapty-bom", version.ref = "adaptyBom" }
adapty = { module = "io.adapty:android-sdk" }

// Only add this line if you plan to use Paywall Builder:
adapty-ui = { module = "io.adapty:android-ui" }

//module-level build.gradle.kts

dependencies {
    ...
    implementation(platform(libs.adapty.bom))
    implementation(libs.adapty)

    // Only add this line if you plan to use Paywall Builder:
    implementation(libs.adapty.ui)
}

Если зависимость не разрешается, убедитесь, что в ваших Gradle-скриптах есть mavenCentral().

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

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

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

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

Активируйте Adapty SDK в коде вашего приложения.

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

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

Или получите его программно с помощью Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

Или напрямую:

npx adapty auth login
adapty apps list

• Убедитесь, что для инициализации Adapty вы используете Public SDK key — Secret key предназначен только для серверного API.
• SDK-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.

// In your Application class

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Adapty.activate(
            applicationContext,
            AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        )
    }
}

// In your Application class

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Adapty.activate(
            getApplicationContext(),
            new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        );
    }
}

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

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

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

Если вы планируете использовать Paywall Builder, вам нужен модуль AdaptyUI. Он активируется автоматически при активации основного модуля — никаких дополнительных действий не требуется.

Настройка Proguard

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

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

Логирование

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

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

Adapty.logLevel = AdaptyLogLevel.VERBOSE
//recommended for development and the first production release

Adapty.setLogLevel(AdaptyLogLevel.VERBOSE);
//recommended for development and the first production release

Перенаправление сообщений системы логирования

Если по какой-то причине вам нужно отправлять сообщения от Adapty в вашу систему или сохранять их в файл, вы можете переопределить поведение по умолчанию:

Adapty.setLogHandler { level, message ->
    //handle the log
}

Adapty.setLogHandler((level, message) -> {
    //handle the log
});

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

Adapty не хранит персональные данные пользователей, если только вы не передаёте их явно. При этом вы можете настроить дополнительные политики безопасности данных для соответствия требованиям стора или законодательства отдельных стран.

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

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

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build();

Отключение сбора и передачи рекламного идентификатора (Ad ID)

При активации модуля Adapty установите adIdCollectionDisabled в значение true, чтобы отключить сбор рекламного идентификатора пользователя. Значение по умолчанию — false. Используйте этот параметр для соблюдения требований Play Store, чтобы избежать показа запроса разрешения на доступ к идентификатору рекламы, или если ваше приложение не требует атрибуции рекламы или аналитики на основе Ad ID.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build();

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

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

val cacheConfig = MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(3.days)
    .build()

AdaptyUI.configureMediaCache(cacheConfig)

MediaCacheConfiguration cacheConfig = new MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(TimeInterval.days(3))
    .build();

AdaptyUI.configureMediaCache(cacheConfig);

Параметры:

Задайте обфусцированные идентификаторы аккаунта

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

Задавать такие идентификаторы может потребоваться, если приложение работает с чувствительными данными пользователей или если вы обязаны соблюдать определённые нормы конфиденциальности. Обфусцированные идентификаторы позволяют Google Play отслеживать покупки, не раскрывая реальные пользовательские идентификаторы.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build();

Запуск Adapty в другом процессе

По умолчанию Adapty может работать только в главном процессе вашего приложения. Если ваше приложение использует несколько процессов, инициализируйте Adapty только один раз — иначе возможно непредсказуемое поведение.

Если вам нужно запустить Adapty в другом процессе, укажите его в конфигурации:

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build();

Если вы попытаетесь активировать Adapty в другом процессе, не задав это значение, SDK выведет предупреждение и пропустит активацию.

Включение локальных уровней доступа

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

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(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/sample_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules) Чтобы решить эту проблему, вам нужно:

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

• Объединить правила резервного копирования из Adapty и других SDK в один XML-файл (или пару файлов для Android 12+).

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

Если оно ещё не добавлено, добавьте пространство имён tools в корневой тег <manifest>:

<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-файлы в директории app/src/main/res/xml/, которые объединяют правила 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"/>



</full-backup-content>

С такой настройкой:

• Исключения резервного копирования Adapty (AdaptySDKPrefs.xml) сохраняются.

• Исключения других SDK (например, appsflyer-data) также применяются.

• Инструмент слияния манифестов использует конфигурацию вашего приложения и больше не завершается ошибкой из-за конфликтующих атрибутов резервного копирования.

Ошибки покупок после возврата из другого приложения

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

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

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

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