Установка и настройка Unity SDK
SDK Adapty включает два ключевых модуля для бесшовной интеграции в ваше приложение Unity:
- Core Adapty: Основной SDK, необходимый для корректной работы Adapty в вашем приложении.
- AdaptyUI: Этот модуль отвечает за отображение флоу, а также пейволов, созданных в старом билдере.
Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наше демо-приложение, в котором показана полная настройка: отображение пейволов, совершение покупок и другие базовые функции.
Требования
Adapty SDK поддерживает iOS 13.0+, однако для работы с пейволами, созданными в Paywall Builder, требуется iOS 15.0+. Adapty SDK 4.1 — который добавляет поддержку флоу — требует iOS 15.0+ для всего приложения: валидатор сборки в Unity Editor блокирует iOS-сборку, если deployment target ниже этой версии. Для сборки под iOS с SDK 4.x также требуется Xcode 26 или новее — нативный iOS SDK, добавляемый в виде Swift-пакета, собирается с использованием Swift tools 6.2.
Adapty SDK 4.3.0 и выше требует Unity 6.0 (6000.0) или новее. На Unity 2022.3 используйте Adapty SDK 4.1.x.
Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. Гайд по быстрому старту описывает все необходимые шаги.
Зависимости
Adapty SDK работает со следующими версиями Google Play Billing Library на Android:
| Версия Adapty SDK | Версия Billing Library |
|---|---|
| 3.17.0 и выше | v8 |
| 3.15.0–3.15.2 | v7 по умолчанию, v8 если другая зависимость её повышает |
Совместимость с версией Billing Library не означает, что Adapty поддерживает все функции, введённые Google в этой версии. Прежде чем использовать новую возможность биллинга Google Play, ознакомьтесь с разделом Продукт в Play Store.
Установка Adapty SDK
Мы всегда рекомендуем устанавливать последнюю доступную версию SDK — в ней содержатся актуальные исправления и улучшения.
Выберите удобный способ установки:
После установки SDK выполните следующие шаги:
-
Установите плагин External Dependency Manager (EDM). SDK Adapty использует его для управления зависимостями iOS и зависимостями Android gradle.
-
После установки EDM может потребоваться запустить менеджер зависимостей:
Assets -> External Dependency Manager -> Android Resolver -> Force Resolveи
Assets -> External Dependency Manager -> iOS Resolver -> Install Cocoapods -
При сборке Unity-проекта для iOS вы получите файл
Unity-iPhone.xcworkspace, который необходимо открывать вместоUnity-iPhone.xcodeproj, иначе зависимости Cocoapods не будут использоваться.
Adapty SDK 4.1
SDK 4.1 — добавляющий поддержку флоу — это первый стабильный релиз ветки 4.x. Чтобы установить его через Unity Package Manager, добавьте тег версии к Git URL:
https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0
Если вы устанавливаете через пакет Unity, скачайте adapty-unity-plugin-4.1.0.unitypackage из релиза 4.1.0.
Два изменения в настройке сборки появились в версии 4.x — нативный iOS SDK Adapty объявлен как удалённый Swift-пакет и больше не устанавливается через CocoaPods:
- Обновите External Dependency Manager до версии 1.2.188 или выше — более ранние версии не поддерживают зависимости Swift Package Manager. Именно эту версию SDK 4.1 объявляет как peer dependency, поэтому Unity предупредит вас, если в проекте установлена более старая версия.
- Шаги с CocoaPods выше (
iOS Resolver -> Install Cocoapods, открытиеUnity-iPhone.xcworkspace) относятся только к SDK 3.x. На SDK 4.1 EDM автоматически добавляет Swift-пакет в сгенерированный Xcode-проект. - Установите iOS deployment target на 15.0 или выше. Валидатор сборки в Unity Editor блокирует iOS-сборку, если это требование не выполнено.
Полный список изменений в ветке 4.x смотрите в руководстве по миграции.
Adapty SDK 4.3
SDK 4.3 добавляет тарифные планы с обязательством, сохранение представлений флоу, предзагрузку флоу и управление сообщениями стора. Требуется Unity 6.0 или выше. Для установки через Unity Package Manager добавьте тег версии к Git URL:
https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.3.0-beta.1
Если вы устанавливаете через Unity package, скачайте adapty-unity-plugin-4.3.0-beta.1.unitypackage из релиза 4.3.0-beta.1. Перед импортом удалите папку Assets/AdaptySDK/Plugins/Android/Local: импорт .unitypackage никогда не удаляет файлы, а SDK 4.3 больше не включает внутреннюю Android Java-обёртку, которая хранилась в этой папке.
Если вы обновляете Unity до версии 6 до обновления SDK, оставьте Application Entry Point в значении Activity для Android: Adapty SDK 4.1.x не работает с GameActivity. SDK 4.3 работает с обоими точками входа.
Смотрите руководство по миграции с описанием изменений, требующих обновления кода.
Активация модуля Adapty в SDK
Активируйте Adapty SDK в коде вашего приложения.
SDK Adapty нужно активировать только один раз в приложении.
Чтобы получить Public SDK Key:
- Откройте дашборд Adapty и перейдите в App settings → General.
- В разделе Api keys скопируйте Public SDK Key (НЕ Secret Key).
- Замените
"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-ключи уникальны для каждого приложения, поэтому если у вас несколько приложений, выберите нужный ключ.
using UnityEngine;
using AdaptySDK;
public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
void Start() {
DontDestroyOnLoad(this.gameObject);
Adapty.SetEventListener(this);
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");
Adapty.Activate(builder.Build(), (error) => {
if (error != null) {
// handle the error
return;
}
});
}
public void OnLoadLatestProfile(AdaptyProfile profile) { }
public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
public void OnInstallationDetailsFail(AdaptyError error) { }
}
В SDK 4.1 интерфейсы слушателей следуют соглашению об именовании C# с префиксом I — реализуйте IAdaptyEventListener вместо AdaptyEventListener — и интерфейс требует ещё одного метода, OnReceivePromotedPurchase. Смотрите руководство по миграции.
Дождитесь колбэка завершения Activate, прежде чем вызывать любые другие методы Adapty SDK. Полная последовательность описана в разделе Порядок вызовов в Unity SDK.
Настройка прослушивания событий
Создайте скрипт для прослушивания событий Adapty. Назовите его AdaptyListener в вашей сцене. Рекомендуем использовать метод DontDestroyOnLoad для этого объекта, чтобы он сохранялся на протяжении всего жизненного цикла приложения.
Adapty использует пространство имён AdaptySDK. В начале файлов скриптов, использующих Adapty SDK, можно добавить:
using AdaptySDK;
Подпишитесь на события Adapty:
using UnityEngine;
using AdaptySDK;
public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
public void OnLoadLatestProfile(AdaptyProfile profile) {
// handle updated profile data
}
public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
public void OnInstallationDetailsFail(AdaptyError error) { }
}
Мы рекомендуем настроить Script Execution Order так, чтобы AdaptyListener выполнялся раньше Default Time. Это обеспечит инициализацию Adapty как можно раньше.
Теперь настройте пейволы в своём приложении:
- Если вы используете Flow & Paywall Builder, сначала активируйте модуль AdaptyUI ниже, а затем следуйте быстрому старту.
- Если вы создаёте собственный интерфейс пейвола, см. быстрый старт для пользовательских пейволов.
Активация модуля AdaptyUI в SDK Adapty
Если вы планируете использовать Flow & Paywall Builder и установили модуль AdaptyUI, его необходимо активировать. Это можно сделать при конфигурации:
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetActivateUI(true);
Дополнительная настройка
Логирование
Настройка системы логирования
Adapty логирует ошибки и другую важную информацию, чтобы помочь вам разобраться в происходящем. Доступны следующие уровни логирования:
| Level | Description |
|---|---|
error | Будут записываться только ошибки |
warn | Будут записываться ошибки и сообщения от SDK, которые не вызывают критических ошибок, но заслуживают внимания |
info | Будут записываться ошибки, предупреждения и различные информационные сообщения |
verbose | Будет записываться любая дополнительная информация, которая может быть полезна при отладке: вызовы функций, запросы к API и т. д. |
Уровень логирования можно задать при настройке Adapty в вашем приложении:
// 'verbose' is recommended for development and the first production release
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");
builder.LogLevel = AdaptyLogLevel.Verbose;
Уровень логирования также можно изменить во время работы приложения:
Adapty.SetLogLevel(AdaptyLogLevel.Verbose, (error) => {
// handle result
});
Политики обработки данных
Adapty не хранит персональные данные ваших пользователей, если вы явно их не передаёте. При этом вы можете настроить дополнительные политики безопасности данных в соответствии с требованиями стора или законодательства конкретной страны.
Отключение сбора и передачи IP-адресов
При активации модуля Adapty установите SetIPAddressCollectionDisabled в значение true, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — false.
Используйте этот параметр для защиты конфиденциальности пользователей, соблюдения региональных требований по защите данных (например, GDPR или CCPA) или для сокращения избыточного сбора данных в случаях, когда функции на основе IP-адреса не нужны вашему приложению.
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetIPAddressCollectionDisabled(true);
Отключение сбора и передачи рекламного идентификатора
При активации модуля Adapty установите SetAppleIDFACollectionDisabled и/или SetGoogleAdvertisingIdCollectionDisabled в значение true, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — false.
Используйте этот параметр для соблюдения политик App Store/Google Play, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не требует рекламной атрибуции или аналитики на основе рекламных идентификаторов.
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetAppleIDFACollectionDisabled(true)
.SetGoogleAdvertisingIdCollectionDisabled(true);
Настройка конфигурации медиакеша для AdaptyUI
По умолчанию AdaptyUI кеширует медиафайлы (изображения и видео) для повышения производительности и снижения потребления трафика. Вы можете настроить параметры кеша, передав собственную конфигурацию.
Используйте SetAdaptyUIMediaCache, чтобы переопределить настройки кеша по умолчанию:
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetAdaptyUIMediaCache(
100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
null, // MemoryStorageCountLimit
100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
);
Параметры:
| Параметр | Обязательный | Описание |
|---|---|---|
| memoryStorageTotalCostLimit | optional | Общий размер кэша в памяти в байтах. По умолчанию используется платформозависимое значение. |
| memoryStorageCountLimit | optional | Максимальное количество элементов в памяти. По умолчанию используется платформозависимое значение. |
| diskStorageSizeLimit | optional | Максимальный размер файлов на диске в байтах. По умолчанию используется платформозависимое значение. |
Включение локальных уровней доступа (Android)
По умолчанию локальные уровни доступа включены на iOS и отключены на Android. Чтобы включить их и на Android, установите SetGoogleLocalAccessLevelAllowed в true:
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetGoogleLocalAccessLevelAllowed(true);
Очистка данных при восстановлении из резервной копии
Когда SetAppleClearDataOnBackup установлен в true, SDK обнаруживает восстановление приложения из резервной копии iCloud и удаляет все локально сохранённые данные SDK, включая кешированную информацию о профиле, данные о продуктах и пейволы. После этого SDK инициализируется с чистым состоянием. Значение по умолчанию — false.
Удаляется только локальный кеш SDK. История транзакций с Apple и пользовательские данные на серверах Adapty остаются неизменными.
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetAppleClearDataOnBackup(true);
Обработка сообщений стора
Этот параметр доступен начиная с версии SDK 4.3.0.
По умолчанию StoreKit самостоятельно показывает сообщения App Store — запросы согласия на повышение цены, уведомления о проблемах с оплатой и win-back offer — пока приложение открыто, а SDK запрашивает сообщения Google Play, например уведомления об отклонённых платежах, каждый раз при запуске Activity вашего приложения после активации. Чтобы управлять моментом отображения этих сообщений, вызовите SetStoreMessagesHandling со значением AdaptyStoreMessagesHandling.Manual. Значение по умолчанию — AdaptyStoreMessagesHandling.Auto.
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetStoreMessagesHandling(AdaptyStoreMessagesHandling.Manual);
В ручном режиме сторы не показывают сообщения самостоятельно, поэтому ваше приложение должно вызывать Adapty.ShowStoreMessages. Подробнее — в разделе Управление сообщениями стора.
Включите Adapty Attribution
Этот параметр доступен начиная с версии SDK 4.1.
Если вы используете Adapty Attribution, установите SetAdaptyAttributionEnabled в true при активации SDK. Значение по умолчанию — false: без этого параметра SDK не регистрирует установки и не передаёт данные об установке в ваше приложение. В версиях SDK ниже 4.1 Adapty Attribution включается автоматически.
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
.SetAdaptyAttributionEnabled(true);
Устранение неполадок
Правила резервного копирования 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)
Эти изменения нужно вносить в директории Android-платформы вашего проекта (как правило, это папка android/).
Чтобы решить эту проблему, нужно:
-
Указать слиянию манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием.
-
Создать файлы правил резервного копирования, которые объединяют правила 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, которые поддерживает ваше приложение.
В приведённых примерах в качестве стороннего SDK используется AppsFlyer. Замените или добавьте правила для других SDK, которые вы используете в своём приложении.
Для 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"/>
В Unity применяйте эти изменения в Assets/Plugins/Android/AndroidManifest.xml и создавайте файлы правил резервного копирования в Assets/Plugins/Android/res/xml/.
Покупки завершаются с ошибкой после возврата из другого приложения в Android
Если Activity, запускающий флоу покупки, использует нестандартный launchMode, Android может пересоздать или повторно использовать его некорректно при возврате пользователя из Google Play, банковского приложения или браузера. В результате результат покупки может быть потерян или расценён как отменённый.
Чтобы покупки работали корректно, используйте для Activity, запускающей флоу покупки, только режимы запуска standard или singleTop — остальные режимы не поддерживаются.
В файле AndroidManifest.xml убедитесь, что Activity, запускающая флоу покупки, настроена на standard или singleTop:
<activity
android:name=".MainActivity"
android:launchMode="standard" />
Приложение падает при отображении пейвола на Android
Если приложение падает на Android при отображении пейвола, возможно, в конфигурации Gradle отсутствует плагин Kotlin. Чтобы добавить его:
-
В разделе Player Settings убедитесь, что выбраны опции Custom Launcher Gradle Template и Custom Base Gradle Template.
-
Добавьте следующую строку в
/Assets/Plugins/Android/launcherTemplate.gradle:apply plugin: 'com.android.application' apply plugin: 'kotlin-android' apply from: 'setupSymbols.gradle' apply from: '../shared/keepUnitySymbols.gradle' -
Добавьте следующую строку в
/Assets/Plugins/Android/baseProjectTemplate.gradle:plugins { // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle // To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version id 'com.android.application' version '8.3.0' apply false id 'com.android.library' version '8.3.0' apply false id 'org.jetbrains.kotlin.android' version '1.8.0' apply false **BUILD_SCRIPT_DEPS** }