--- title: "Capacitor - установка и настройка Adapty SDK" description: "Пошаговое руководство по установке Adapty SDK в Capacitor для приложений с подписками." --- Adapty SDK включает два ключевых модуля для бесшовной интеграции в приложение на Capacitor: - **Core Adapty**: обязательный модуль для работы Adapty в вашем приложении. - **AdaptyUI**: нужен, если вы используете [Adapty Paywall Builder](adapty-paywall-builder) — удобный инструмент без написания кода для создания кросс-платформенных пейволов. AdaptyUI активируется автоматически вместе с основным модулем. :::tip Хотите посмотреть на реальный пример интеграции Adapty SDK в мобильное приложение? Загляните в наши [примеры приложений](https://github.com/adaptyteam/AdaptySDK-Capacitor/tree/master/examples): там показана полная настройка, включая отображение пейволов, совершение покупок и другие базовые функции. ::: ## Требования \{#requirements\} [Adapty Capacitor SDK](https://github.com/adaptyteam/AdaptySDK-Capacitor/) поддерживает следующие версии: | Версия Adapty SDK | Версия Capacitor | Версия iOS | |--------------------|-------------------|------------| | 3.16.0+ | 8 | 15.0+ | | 3.15 | 7 | 14.0+ | Capacitor версий 6 и ниже не поддерживается. :::info Adapty совместим с Google Play Billing Library версий до 8.x включительно. По умолчанию Adapty работает с Google Play Billing Library v.7.0.0, но если вам нужна более поздняя версия, вы можете вручную [добавить зависимость](https://developer.android.com/google/play/billing/integrate#dependency). ::: --- no_index: true --- import Callout from '../../../components/Callout.astro'; Установка SDK — это шаг 5 настройки Adapty. Прежде чем покупки заработают в вашем приложении, вам также нужно подключить приложение к сторам, а затем создать продукты, пейвол и плейсмент в дашборде Adapty. [Гайд по быстрому старту](quickstart) описывает все необходимые шаги. ## Установка Adapty SDK \{#install-adapty-sdk\} [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Capacitor.svg?style=flat&logo=capacitor)](https://github.com/adaptyteam/AdaptySDK-Capacitor/releases) Установите Adapty SDK: ```sh npm install @adapty/capacitor npx cap sync ``` ## Активация модуля Adapty SDK \{#activate-adapty-module-of-adapty-sdk\} :::note Adapty SDK нужно активировать только один раз в приложении. ::: Чтобы получить **Public SDK Key**: 1. Откройте дашборд Adapty и перейдите в [**App settings → General**](https://app.adapty.io/settings/general). 2. В разделе **Api keys** скопируйте **Public SDK Key** (не Secret Key). 3. Замените `"YOUR_PUBLIC_SDK_KEY"` в коде на скопированный ключ. :::important - Используйте **Public SDK key** для инициализации Adapty. **Secret key** предназначен только для [серверного API](getting-started-with-server-side-api). - **SDK keys** уникальны для каждого приложения, поэтому при наличии нескольких приложений убедитесь, что выбрали правильный ключ. ::: Скопируйте следующий код в любой файл приложения, чтобы активировать Adapty: ```typescript showLineNumbers try { await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { // verbose logging is recommended for the development purposes and for the first production release logLevel: 'verbose', // in the development environment, use this variable to avoid multiple activation errors. Set it to your development environment variable __ignoreActivationOnFastRefresh: true, } }); console.log('Adapty activated successfully!'); } catch (error) { console.error('Failed to activate Adapty SDK:', error); } ``` :::tip Чтобы избежать ошибок активации в среде разработки, воспользуйтесь [советами](#development-environment-tips). ::: Теперь настройте пейволы в вашем приложении: - Если вы используете [Adapty Paywall Builder](adapty-paywall-builder), следуйте [быстрому старту с Paywall Builder](capacitor-quickstart-paywalls). - Если вы создаёте собственный UI для пейвола, смотрите [быстрый старт для кастомных пейволов](capacitor-quickstart-manual). ## Активация модуля AdaptyUI \{#activate-adaptyui-module-of-adapty-sdk\} Если вы планируете использовать [Paywall Builder](adapty-paywall-builder), вам понадобится модуль AdaptyUI. Он активируется автоматически при активации основного модуля — дополнительных действий не требуется. ## Опциональная настройка \{#optional-setup\} ### Логирование \{#logging\} #### Настройка системы логирования \{#set-up-the-logging-system\} Adapty записывает ошибки и другую важную информацию, чтобы помочь вам разобраться в происходящем. Доступны следующие уровни логирования: | Уровень | Описание | | ---------- | ------------------------------------------------------------ | | `error` | Записываются только ошибки | | `warn` | Записываются ошибки и сообщения SDK, которые не вызывают критических ошибок, но заслуживают внимания | | `info` | Записываются ошибки, предупреждения и различные информационные сообщения | | `verbose` | Записывается любая дополнительная информация, полезная при отладке: вызовы функций, API-запросы и т.д. | Вы можете установить уровень логирования до или во время конфигурации Adapty: ```typescript showLineNumbers // Set log level before activation adapty.setLogLevel({ logLevel: 'verbose' }); // Or set it during configuration await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { logLevel: 'verbose', } }); ``` ### Политики работы с данными \{#data-policies\} Adapty не хранит персональные данные пользователей, если вы явно их не передаёте, но вы можете применить дополнительные политики безопасности данных для соблюдения требований сторов или законодательства конкретной страны. #### Отключение сбора и передачи IP-адресов \{#disable-ip-address-collection-and-sharing\} При активации модуля Adapty установите `ipAddressCollectionDisabled` в `true`, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — `false`. Используйте этот параметр для повышения конфиденциальности пользователей, соблюдения региональных требований по защите данных (например, GDPR или CCPA) или для сокращения ненужного сбора данных, если функции на основе IP-адресов вашему приложению не нужны. ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ipAddressCollectionDisabled: true, } }); ``` #### Отключение сбора и передачи рекламного идентификатора \{#disable-advertising-id-collection-and-sharing\} При активации модуля Adapty установите `ios.idfaCollectionDisabled` (iOS) или `android.adIdCollectionDisabled` (Android) в `true`, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — `false`. Используйте этот параметр для соблюдения политик App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не использует атрибуцию или аналитику на основе рекламных идентификаторов. ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ios: { idfaCollectionDisabled: true, }, android: { adIdCollectionDisabled: true, }, } }); ``` #### Настройка кэша медиа для AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения сетевой нагрузки. Вы можете изменить параметры кэша, задав собственную конфигурацию. Используйте `mediaCache`, чтобы переопределить настройки кэша по умолчанию: ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { mediaCache: { memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes memoryStorageCountLimit: 2147483647, // Optional: max number of items in memory diskStorageSizeLimit: 200 * 1024 * 1024, // Optional: disk cache size in bytes }, } }); ``` Параметры: | Параметр | Обязательный | Описание | |-----------|----------|-------------| | memoryStorageTotalCostLimit | опционально | Общий размер кэша в памяти в байтах. По умолчанию используется платформо-зависимое значение. | | memoryStorageCountLimit | опционально | Максимальное количество элементов в памяти. По умолчанию используется платформо-зависимое значение. | | diskStorageSizeLimit | опционально | Максимальный размер кэша на диске в байтах. По умолчанию используется платформо-зависимое значение. | ### Включение локальных уровней доступа (Android) \{#enable-local-access-levels-android\} По умолчанию [локальные уровни доступа](local-access-levels) включены на iOS и отключены на Android. Чтобы включить их и на Android, установите `localAccessLevelAllowed` в `true`: ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { android: { localAccessLevelAllowed: true, }, } }); ``` ### Очистка данных при восстановлении из резервной копии \{#clear-data-on-backup-restore\} Если `clearDataOnBackup` установлен в `true`, SDK определяет, что приложение восстановлено из резервной копии iCloud, и удаляет все локально сохранённые данные SDK: кэш профиля, информацию о продуктах и пейволы. После этого SDK инициализируется с чистого состояния. Значение по умолчанию — `false`. :::note Удаляется только локальный кэш SDK. История транзакций в Apple и данные пользователя на серверах Adapty остаются без изменений. ::: ```swift showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ios: { clearDataOnBackup: true, }, } }); ``` ## Советы по работе в среде разработки \{#development-environment-tips\} #### Устранение ошибок активации SDK при использовании live-reload в Capacitor \{#troubleshoot-sdk-activation-errors-on-capacitors-live-reload\} При разработке с Adapty SDK в Capacitor вы можете столкнуться с ошибкой: `Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.` Это происходит из-за того, что функция live-reload в Capacitor вызывает несколько активаций в процессе разработки. Чтобы этого избежать, используйте параметр `__ignoreActivationOnFastRefresh`, установив его в флаг режима разработки Capacitor — конкретное значение зависит от используемого бандлера. ```typescript showLineNumbers try { await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { // Set your development environment variable __ignoreActivationOnFastRefresh: true, } }); } catch (error) { console.error('Failed to activate Adapty SDK:', error); // Handle the error appropriately for your app } ``` ## Устранение неполадок \{#troubleshooting\} #### Ошибка минимальной версии iOS \{#minimum-ios-version-error\} Если вы получаете ошибку минимальной версии iOS, обновите Podfile: ```diff -platform :ios, min_ios_version_supported +platform :ios, '14.0' # For core features only # OR +platform :ios, '15.0' # If using paywalls created in the paywall builder ``` #### Правила резервного копирования Android (конфигурация Auto Backup) \{#android-backup-rules-auto-backup-configuration\} Некоторые 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)` :::note Эти изменения нужно вносить в директорию Android-платформы (обычно находится в папке `android/` вашего проекта). ::: Чтобы решить проблему, необходимо: - Указать механизму слияния манифестов использовать значения вашего приложения для атрибутов, связанных с резервным копированием. - Создать файлы правил резервного копирования, объединяющие правила Adapty с правилами других SDK. #### 1. Добавьте пространство имён `tools` в манифест В файле `AndroidManifest.xml` убедитесь, что корневой тег `` включает tools: ```xml ... ``` #### 2. Переопределите атрибуты резервного копирования в `` В том же файле `AndroidManifest.xml` обновите тег ``, чтобы ваше приложение предоставляло итоговые значения и указывало механизму слияния манифестов заменять значения библиотек: ```xml ... ``` Если какой-либо SDK также задаёт `android:allowBackup`, включите его в `tools:replace`: ```xml tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules" ``` #### 3. Создайте объединённые файлы правил резервного копирования Создайте XML-файлы в директории `res/xml/` вашего Android-проекта, объединяющие правила Adapty с правилами других SDK. Android использует разные форматы правил резервного копирования в зависимости от версии ОС, поэтому создание обоих файлов обеспечивает совместимость со всеми версиями Android, которые поддерживает ваше приложение. :::note В примерах ниже в качестве стороннего SDK используется AppsFlyer. Замените или добавьте правила для других SDK, которые используются в вашем приложении. ::: **Для Android 12 и выше** (используется новый формат правил извлечения данных): ```xml title="sample_data_extraction_rules.xml" ``` **Для Android 11 и ниже** (используется устаревший формат полного резервного копирования): ```xml title="sample_backup_rules.xml" :::tip После изменения нативных файлов Android выполните `npx cap sync android`, чтобы Capacitor подхватил обновлённые ресурсы при повторной генерации платформы. ::: #### Покупки не завершаются после возврата из другого приложения на Android \{#purchases-fail-after-returning-from-another-app-in-android\} Если Activity, запускающий процесс покупки, использует нестандартный `launchMode`, Android может некорректно пересоздать или повторно использовать его при возврате пользователя из Google Play, банковского приложения или браузера. Это может привести к потере результата покупки или его обработке как отменённого. Чтобы покупки работали корректно, используйте только режимы запуска `standard` или `singleTop` для Activity, запускающего процесс покупки, и избегайте других режимов. В файле `AndroidManifest.xml` убедитесь, что для Activity, запускающего процесс покупки, установлен режим `standard` или `singleTop`: ```xml ```