--- title: "Установка и настройка Adapty SDK в чистом проекте React Native" description: "Пошаговое руководство по установке Adapty SDK в React Native для приложений с подписками." --- :::important Это руководство распространяется только на **чистые проекты React Native (без Expo)**. Если вы используете **Expo**, следуйте [руководству по установке для Expo](sdk-installation-react-native-expo). ::: Adapty SDK включает два ключевых модуля для бесшовной интеграции в ваше приложение React Native: - **Core Adapty**: обязательный модуль для корректной работы Adapty в вашем приложении. - **AdaptyUI**: нужен, если вы используете [Adapty Paywall Builder](adapty-paywall-builder) — удобный no-code инструмент для создания кроссплатформенных пейволов. AdaptyUI активируется автоматически вместе с основным модулем. :::tip Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши [примеры приложений](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples) — они демонстрируют полную настройку: отображение пейволов, совершение покупок и другую базовую функциональность. ::: ## Требования \{#requirements\} Adapty React Native SDK поддерживает iOS 13.0+, однако использование пейволов, созданных в [Adapty Paywall Builder](adapty-paywall-builder), требует iOS 15.0+. :::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-React-Native.svg?style=flat&logo=react)](https://github.com/adaptyteam/AdaptySDK-React-Native/releases) 1. Установите Adapty SDK (при этом автоматически установится и `@adapty/core`): ```sh showLineNumbers title="Shell" # using npm npm install react-native-adapty # or using yarn yarn add react-native-adapty ``` 2. Для iOS установите поды: ```sh showLineNumbers title="Shell" cd ios && pod install ```
Для Android, если ваша версия React Native ниже 0.73.0 (нажмите, чтобы раскрыть) Обновите файл `/android/build.gradle`. Убедитесь, что там есть зависимость `kotlin-gradle-plugin:1.8.0` или более новая: ```groovy showLineNumbers title="/android/build.gradle" ... buildscript { ... dependencies { ... classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0" } } ... ```
## Активация модуля Adapty из Adapty SDK \{#activate-adapty-module-of-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** уникальны для каждого приложения, поэтому при наличии нескольких приложений убедитесь, что выбрали правильный ключ. ::: Скопируйте следующий код в `App.tsx` для активации Adapty: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY'); ``` :::tip Чтобы избежать ошибок активации в среде разработки, используйте [советы ниже](#development-environment-tips). ::: Теперь настройте пейволы в своём приложении: - Если вы используете [Adapty Paywall Builder](adapty-paywall-builder), следуйте [быстрому старту с Paywall Builder](react-native-quickstart-paywalls). - Если вы создаёте собственный UI пейвола, смотрите [быстрый старт для кастомных пейволов](react-native-quickstart-manual). ## Активация модуля AdaptyUI из Adapty SDK \{#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 title="App.tsx" // Set log level before activation // 'verbose' is recommended for development and the first production release adapty.setLogLevel('verbose'); // Or set it during configuration adapty.activate('YOUR_PUBLIC_SDK_KEY', { logLevel: 'verbose', }); ``` ### Политики работы с данными \{#data-policies\} Adapty не хранит персональные данные ваших пользователей, если вы явно их не передаёте, но вы можете внедрить дополнительные политики безопасности данных для соответствия требованиям сторов или местному законодательству. #### Отключение сбора и передачи IP-адресов \{#disable-ip-address-collection-and-sharing\} При активации модуля Adapty установите `ipAddressCollectionDisabled` в `true`, чтобы отключить сбор и передачу IP-адресов пользователей. Значение по умолчанию — `false`. Используйте этот параметр для повышения конфиденциальности пользователей, соблюдения региональных требований по защите данных (например, GDPR или CCPA) или чтобы сократить сбор ненужных данных, если функции на основе IP не нужны вашему приложению. ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { 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 title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { ios: { idfaCollectionDisabled: true, }, android: { adIdCollectionDisabled: true, }, }); ``` #### Настройка конфигурации кэша медиа для AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} По умолчанию AdaptyUI кэширует медиафайлы (изображения и видео) для повышения производительности и снижения сетевой нагрузки. Вы можете настроить параметры кэша, указав собственную конфигурацию. Используйте `mediaCache`, чтобы переопределить настройки кэша по умолчанию: ```typescript adapty.activate('YOUR_PUBLIC_SDK_KEY', { 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 title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { android: { localAccessLevelAllowed: true, }, }); ``` ### Очистка данных при восстановлении из резервной копии \{#clear-data-on-backup-restore\} Когда `clearDataOnBackup` установлен в `true`, SDK обнаруживает восстановление приложения из резервной копии iCloud и удаляет все локально хранящиеся данные SDK, включая кэшированную информацию профиля, сведения о продуктах и пейволы. После этого SDK инициализируется в чистом состоянии. Значение по умолчанию — `false`. :::note Удаляется только локальный кэш SDK. История транзакций в Apple и пользовательские данные на серверах Adapty остаются без изменений. ::: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { ios: { clearDataOnBackup: true }, }); ``` ## Советы для среды разработки \{#development-environment-tips\} #### Отложенная активация SDK для разработки \{#delay-sdk-activation-for-development-purposes\} При активации SDK Adapty заранее загружает все необходимые пользовательские данные, обеспечивая более быстрый доступ к актуальной информации. Однако в симуляторе iOS это может стать проблемой, поскольку он часто запрашивает аутентификацию во время разработки. Adapty не может управлять процессом аутентификации StoreKit, но может отложить собственные запросы на получение актуальных пользовательских данных. Включив свойство `__debugDeferActivation`, вызов активации будет удерживаться до следующего обращения к Adapty SDK. Это предотвращает лишние запросы аутентификационных данных, если они не нужны. Важно учитывать, что **эта функция предназначена только для разработки**, так как не охватывает все возможные сценарии работы пользователей. В продакшне откладывать активацию не следует: на реальных устройствах аутентификационные данные обычно сохраняются и не запрашиваются повторно. Рекомендуемый способ использования: ```typescript showLineNumbers title="Typescript" try { adapty.activate('PUBLIC_SDK_KEY', { __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library }); } catch (error) { console.error('Failed to activate Adapty SDK:', error); // Handle the error appropriately for your app } ``` #### Устранение ошибок активации SDK при использовании Fast Refresh в React Native \{#troubleshoot-sdk-activation-errors-on-react-natives-fast-refresh\} При разработке с Adapty SDK в React Native вы можете столкнуться с ошибкой: `Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.` Это происходит из-за того, что функция быстрого обновления React Native вызывает несколько активаций во время разработки. Чтобы этого избежать, используйте опцию `__ignoreActivationOnFastRefresh`, установив её в `__DEV__` (флаг режима разработки React Native). ```typescript showLineNumbers title="Typescript" try { adapty.activate('PUBLIC_SDK_KEY', { __ignoreActivationOnFastRefresh: __DEV__, }); } catch (error) { console.error('Failed to activate Adapty SDK:', error); // Handle the error appropriately for your app } ``` #### Настройка mock-режима для локального тестирования \{#set-up-mock-mode-for-local-testing\} Для локальной разработки и тестирования можно включить mock-режим, чтобы обойтись без sandbox-аккаунтов App Store/Google Play и ускорить итерации. В mock-режиме нативные модули Adapty полностью обходятся, а вместо них возвращаются симулированные данные. :::important Mock-режим **не** предназначен для тестирования реальных покупок: - Он **не открывает** процессы покупки в App Store / Google Play и **не создаёт** реальных транзакций. - Он **не отображает** пейволы/онбординги, созданные с помощью **Adapty Paywall Builder (AdaptyUI)**. - Нативные модули Adapty **полностью обходятся** — даже отсутствие нативных файлов SDK в сборке Xcode/Android или неверный API-ключ не вызовут ошибок. - Данные на серверы Adapty не отправляются. Для тестирования реальных покупок и пейволов Paywall Builder отключите mock-режим и используйте sandbox-аккаунты. ::: Чтобы включить mock-режим, установите `enableMock` в `true`: ```typescript showLineNumbers title="App.tsx" adapty.activate('YOUR_PUBLIC_SDK_KEY', { enableMock: true, }); ``` Когда mock-режим активен: - Все методы Adapty возвращают mock-данные без сетевых запросов к серверам Adapty. - По умолчанию начальный mock-профиль не имеет активных подписок. - По умолчанию `makePurchase(...)` симулирует успешную покупку и предоставляет премиум-доступ. Вы можете настроить mock-данные с помощью `mockConfig` при активации. Формат конфигурации и поддерживаемые параметры смотрите [здесь](https://react-native.adapty.io/interfaces/adaptymockconfig). ```typescript showLineNumbers title="App.tsx" try { await adapty.activate('YOUR_PUBLIC_SDK_KEY', { mockConfig: { // Customize the initial mock profile (optional) }, }); } catch (error) { console.error('Failed to activate Adapty SDK:', error); } ``` Если вам нужно вызвать методы SDK до активации (например, `isActivated()` или `setLogLevel()`), используйте `enableMock()` перед `activate()`. Если бридж уже инициализирован, этот метод ничего не делает. ```typescript showLineNumbers title="App.tsx" adapty.enableMock(); // Optional: pass mockConfig to customize mock data // Now you can call methods before activation await adapty.activate('YOUR_PUBLIC_SDK_KEY'); ``` ## Устранение неполадок \{#troubleshooting\} #### Ошибка минимальной версии iOS \{#minimum-ios-version-error\} Если вы получаете ошибку минимальной версии iOS, обновите Podfile: ```diff -platform :ios, min_ios_version_supported +platform :ios, '13.0' # For core features only # OR +platform :ios, '15.0' # If using paywalls created in the paywall builder ``` #### Конфликт манифеста Android Auto Backup \{#android-auto-backup-manifest-conflict\} Некоторые 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" #### Покупки прерываются после возврата из другого приложения на Android \{#purchases-fail-after-returning-from-another-app-in-android\} Если Activity, запускающий процесс покупки, использует нестандартный `launchMode`, Android может некорректно пересоздать или повторно использовать его при возврате пользователя из Google Play, банковского приложения или браузера. Это может привести к потере результата покупки или трактовке её как отменённой. Чтобы покупки работали корректно, используйте только режимы запуска `standard` или `singleTop` для Activity, запускающего процесс покупки, и избегайте любых других режимов. В файле `AndroidManifest.xml` убедитесь, что для Activity, запускающего процесс покупки, задан режим `standard` или `singleTop`: ```xml ```