Установка и настройка Adapty SDK в чистом проекте React Native

Adapty SDK включает два ключевых модуля для интеграции в приложение React Native:

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

Требования

Adapty React Native SDK поддерживает iOS 13.0+, однако использование пейволов, созданных в Adapty Paywall Builder, требует iOS 15.0+.

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

1. Установите Adapty SDK (при этом автоматически установится @adapty/core):

   # using npm
   npm install react-native-adapty
   
   # or using yarn
   yarn add react-native-adapty  

2. Для iOS установите поды:

   cd ios && pod install

...
buildscript {
  ...
  dependencies {
    ...
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
  }
}
...

Активируйте модуль Adapty SDK

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

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

Скопируйте следующий код в App.tsx, чтобы активировать Adapty:

adapty.activate('YOUR_PUBLIC_SDK_KEY');

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

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

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

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

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

Логирование

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

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

// 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',
});

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

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

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

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

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ipAddressCollectionDisabled: true,
});

Отключить сбор и передачу рекламного идентификатора

При активации модуля Adapty установите ios.idfaCollectionDisabled (iOS) или android.adIdCollectionDisabled (Android) в значение true, чтобы отключить сбор рекламных идентификаторов. Значение по умолчанию — false.

Используйте этот параметр для соблюдения политик App Store/Play Store, чтобы не вызывать запрос App Tracking Transparency, или если ваше приложение не использует рекламную атрибуцию или аналитику на основе рекламных идентификаторов.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ios: {
    idfaCollectionDisabled: true,      
  },
  android: {
    adIdCollectionDisabled: true,      
  },
});

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

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

Используйте mediaCache, чтобы переопределить настройки кэша по умолчанию:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  mediaCache: {
    memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Опционально: размер кэша в памяти в байтах
    memoryStorageCountLimit: 2147483647,            // Опционально: макс. количество элементов в памяти
    diskStorageSizeLimit: 200 * 1024 * 1024,       // Опционально: размер кэша на диске в байтах
  },
});

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

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

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  android: {
     localAccessLevelAllowed: true,      
  },
});

Очистка данных при восстановлении из резервной копии

Когда clearDataOnBackup установлен в true, SDK обнаруживает восстановление приложения из резервной копии iCloud и удаляет все локально хранящиеся данные SDK, включая кэшированную информацию профиля, сведения о продуктах и пейволы. После этого SDK инициализируется в чистом состоянии. Значение по умолчанию — false.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   ios: {
      clearDataOnBackup: true
   },
});

Советы по настройке среды разработки

Откладывание активации SDK для целей разработки

При активации SDK Adapty заранее загружает все необходимые данные о пользователе, что обеспечивает более быстрый доступ к актуальной информации.

Однако в симуляторе iOS это может создавать неудобства: во время разработки симулятор часто запрашивает аутентификацию. Adapty не может управлять процессом аутентификации StoreKit, но может отложить запросы, которые SDK выполняет для получения свежих данных. Включив свойство __debugDeferActivation, вызов активации откладывается до следующего вызова Adapty SDK. Это предотвращает лишние запросы данных аутентификации, если они не нужны.

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

Рекомендуемый подход к использованию:

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' из любой сторонней библиотеки
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Обработайте ошибку соответствующим образом
}

Устранение ошибок активации SDK при Fast Refresh в React Native

При разработке с 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).

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-режима для локального тестирования

Для локальной разработки и тестирования можно включить mock-режим, чтобы не использовать sandbox-аккаунты App Store/Google Play и ускорить итерации. Mock-режим полностью обходит нативные модули Adapty и возвращает симулированные данные.

Чтобы включить mock-режим, установите enableMock в true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  enableMock: true,
});

Когда активен режим mock:

• Все методы Adapty возвращают mock-данные без сетевых запросов к серверам Adapty.
• По умолчанию начальный mock-профиль не имеет активных подписок.
• По умолчанию makePurchase(...) симулирует успешную покупку и предоставляет премиум-доступ.

Вы можете настроить mock-данные с помощью mockConfig при активации. Формат конфига и поддерживаемые параметры описаны здесь.

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(). Если бридж уже инициализирован, этот метод ничего не делает.

adapty.enableMock(); // Опционально: передайте mockConfig для настройки тестовых данных

// Теперь можно вызывать методы до активации

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

Устранение неполадок

Ошибка минимальной версии iOS

Если возникает ошибка минимальной версии iOS, обновите Podfile:

-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

Некоторые 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)

Чтобы решить проблему, необходимо:

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

• Создать файлы правил резервного копирования, объединяющие правила 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, которые поддерживает ваше приложение.

Для 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"/>

    

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

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

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

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

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

Ошибки сборки Swift 6, вызванные переопределением SWIFT_VERSION в Podfile

При сборке React Native приложения для iOS могут появляться ошибки компиляции Swift 6 в pod-таргетах Adapty. Типичные симптомы: несовпадение @Sendable в AdaptyUIBuilderLogic, отсутствие соответствия Sendable для типов Adapty или ошибки изоляции актора. Поды Adapty объявляют s.swift_version = '6.0' и требуют Swift 6 для сборки. Ваш собственный код приложения может оставаться на Swift 5 — только целевые поды Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) нужно собирать с Swift 6.

Самая распространённая причина — хук post_install в ios/Podfile, который перезаписывает SWIFT_VERSION для каждого пода:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Исправление: Исключите pod-таргеты Adapty из переопределения:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Затем выполните pod install из директории ios/ и пересоберите проект.

Для проверки откройте ios/Pods/Pods.xcodeproj, выберите таргет пода Adapty → Build Settings → Swift Language Version. Там должно быть Swift 6.