--- title: "Установка и настройка Adapty React Native SDK в проекте Expo" description: "Пошаговое руководство по установке Adapty React Native SDK в проекте Expo для приложений на основе подписок." --- :::important Это руководство описывает установку и настройку Adapty React Native SDK **в проекте Expo**. Если вы используете **чистый React Native (без Expo)**, следуйте [руководству по установке для React Native](sdk-installation-react-native-pure). ::: Adapty SDK включает два ключевых модуля для интеграции в ваше React Native-приложение: - **Core Adapty**: обязательный модуль для работы Adapty в вашем приложении. - **AdaptyUI**: нужен, если вы используете [Adapty Paywall Builder](adapty-paywall-builder) — удобный no-code инструмент для создания кросс-платформенных пейволов. AdaptyUI активируется автоматически вместе с основным модулем. Если вам нужен полный туториал по реализации IAP в React Native-приложении, загляните [сюда](https://adapty.io/blog/react-native-in-app-purchases-tutorial/). :::tip Хотите увидеть реальный пример интеграции Adapty SDK в Expo-приложение? Посмотрите наши примеры: - [Пример сборки Expo Dev Build](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples/FocusJournalExpo) — с полным функционалом: реальные покупки и Paywall Builder - [Пример Expo Go & Web](https://github.com/adaptyteam/AdaptySDK-React-Native/tree/master/examples/ExpoGoWebMock) — для тестирования в режиме mock ::: Полный разбор реализации также доступен в видео:
## Требования \{#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). В Expo это можно сделать во время prebuild или через config plugin. ::: --- 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) :::important Для использования Adapty в проекте Expo необходим [Expo Dev Client](https://docs.expo.dev/versions/latest/sdk/dev-client/) (кастомная dev-сборка). Expo Go не поддерживает кастомные нативные модули, поэтому в нём можно использовать только [**режим mock**](#set-up-mock-mode-for-expo-go--expo-web) для разработки UI/логики (без реальных покупок и без рендеринга AdaptyUI/Paywall Builder). ::: 1. Установите Adapty SDK (это также автоматически установит `@adapty/core`): ```sh npx expo install react-native-adapty npx expo prebuild ``` 2. Соберите приложение для разработки с помощью EAS или локальной сборки: ```sh # For iOS eas build --profile development --platform ios # For Android eas build --profile development --platform android ``` ```sh # For iOS npx expo run:ios # For Android npx expo run:android ``` 3. Запустите dev-сервер: ```sh npx expo start --dev-client ``` ## Активация модуля 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\} #### Настройка режима mock для Expo Go / Expo Web \{#set-up-mock-mode-for-expo-go--expo-web\} В Expo Go и Expo Web нет доступа к нативным модулям Adapty. Чтобы избежать ошибок во время выполнения и при этом иметь возможность разрабатывать и тестировать UI и логику пейволов, Adapty предоставляет **режим mock**. ::::important Режим mock **не** предназначен для тестирования реальных покупок: - Он **не открывает** флоу покупок в App Store / Google Play и **не создаёт** реальные транзакции. - Он **не рендерит** пейволы/онбординги, созданные в **Adapty Paywall Builder (AdaptyUI)**. - Нативные модули Adapty **полностью обходятся** — даже отсутствие нативных файлов SDK в сборке Xcode/Android или неверный API-ключ не вызовут ошибок. Для тестирования реальных покупок и пейволов Paywall Builder используйте Expo Dev Client / продакшн-сборку, в которой режим mock автоматически отключён. :::: **По умолчанию** SDK автоматически определяет среду Expo Go и веб-среду и включает режим mock. Никакой дополнительной настройки не требуется, если вы не хотите изменить mock-данные. Когда режим 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'); ``` #### Отложенная активация SDK для целей разработки \{#delay-sdk-activation-for-development-purposes\} Adapty заранее загружает все необходимые данные пользователя при активации SDK, что обеспечивает более быстрый доступ к актуальным данным. Однако в симуляторе iOS это может быть проблемой, поскольку во время разработки симулятор часто запрашивает аутентификацию. Adapty не может управлять флоу аутентификации StoreKit, но может отложить запросы на получение актуальных данных пользователя. Если включить свойство `__debugDeferActivation`, вызов activate будет заморожен до следующего обращения к 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.` Это происходит потому, что функция быстрого обновления (fast refresh) в 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 } ``` ## Решение проблем \{#troubleshooting\} #### Ошибка минимальной версии iOS \{#minimum-ios-version-error\} При сборке для iOS может возникнуть ошибка, связанная с **минимальной версией iOS** или deployment target, особенно если вы используете пейволы, созданные в [Adapty Paywall Builder](adapty-paywall-builder), которые требуют **iOS 15.0+**. Поскольку Expo генерирует iOS-проект (включая `Podfile`) во время `expo prebuild`, **не редактируйте `Podfile` напрямую**. Вместо этого настройте deployment target через config plugin `expo-build-properties`. 1. Установите плагин: ```sh npx expo install expo-build-properties ``` 2. Обновите конфигурацию Expo (`app.json` или `app.config.js`), указав deployment target для iOS: ``` { "expo": { // ...other Expo config... "plugins": [ [ "expo-build-properties", { "ios": { // Use "13.0" for core Adapty features only, // or "15.0" if you use paywalls created in the paywall builder. "deploymentTarget": "15.0" } } ], ] } } ``` 3. Пересоздайте нативный iOS-проект и выполните сборку заново: ``` npx expo prebuild --clean npx expo run:ios # or `eas build -p ios` on your CI ``` #### Конфликт манифеста Android Auto Backup \{#android-auto-backup-manifest-conflict\} При использовании Expo с несколькими SDK, которые настраивают Android Auto Backup (например, Adapty, AppsFlyer или expo-secure-store), может возникнуть конфликт при слиянии манифестов. Типичная ошибка выглядит так: `Manifest merger failed : Attribute application@fullBackupContent value=(@xml/secure_store_backup_rules) from AndroidManifest.xml:24:248-306 is also present at [io.adapty:android-sdk:3.12.0] AndroidManifest.xml:9:18-70 value=(@xml/adapty_backup_rules).` Чтобы устранить этот конфликт, позвольте плагину Adapty управлять конфигурацией Android-резервного копирования. Если в вашем проекте также используется `expo-secure-store`, отключите его собственную настройку резервного копирования во избежание дублирования. Вот как настроить `app.json`: ```json title="app.json" { "expo": { "plugins": [ ["react-native-adapty", { "replaceAndroidBackupConfig": true }], ["expo-secure-store", { "configureAndroidBackup": false }] ] } } ``` Опция `replaceAndroidBackupConfig` по умолчанию равна `false`. При включении она передаёт управление правилами резервного копирования Android плагину Adapty. Укажите `"configureAndroidBackup": false`, если используете `expo-secure-store`, чтобы избежать предупреждений — конфигурацией резервного копирования SecureStore теперь будет управлять Adapty. :::important Эта настройка учитывает требования к резервному копированию только для Adapty, AppsFlyer и expo-secure-store. Если другие библиотеки в вашем проекте определяют собственные правила резервного копирования, их нужно настроить вручную. :::