RuStore React Native Remote Config SDK для работы с облачным сервисом конфигурации приложения

🔗 Документация разработчика

Подключение в проект

// HTTPS
npm install git+https://git@gitflic.ru/project/rustore/rustore-react-native-remoteconfig.git

// SSH
npm install git+ssh://git@gitflic.ru/project/rustore/rustore-react-native-remoteconfig.git

Поддерживаемые платформы

Обертка использует ru.rustore.sdk:remoteconfig:10.5.1 на Android и RSRemoteConfig на iOS.

RSRemoteConfig.xcframework не хранится в репозитории. Во время pod install podspec скачивает версию 1.2.2 из Nexus и проверяет SHA-256 из официального Swift Package.

После установки npm-пакета выполните pod install в каталоге iOS-приложения:

cd ios
pod install

Быстрый старт

import RemoteConfigClient, {
  RemoteConfigClientParams,
  RemoteConfigEvents,
  UpdateBehaviour,
  remoteConfigEventEmitter,
} from 'react-native-rustore-remote-config';

// 1. Создание клиента — синхронный вызов, должен выполняться до остальных методов
RemoteConfigClient.createRemoteConfig(
  '11111111-1111-1111-1111-111111111111', // appId из консоли RuStore
  15,                                      // интервал обновления, минуты
  UpdateBehaviour.DEFAULT,
  new RemoteConfigClientParams({ deviceModel: 'SAMSUNG S24' })
);

// 2. Подписка на события клиента
const subscription = remoteConfigEventEmitter.addListener(
  RemoteConfigEvents.INIT_COMPLETE,
  () => console.log('init complete')
);

// 3. Инициализация
try {
  await RemoteConfigClient.init();
} catch (error) {
  console.error(error);
}

// 4. Получение всей конфигурации (все значения — строки)
const config = await RemoteConfigClient.getRemoteConfig();

// 5. Типизированное чтение отдельных значений
const welcome = await RemoteConfigClient.getString('welcome_message');
const enabled = await RemoteConfigClient.getBoolean('feature_enabled');

subscription.remove();

Сценарий использования

Выбор модели обновления

На стартовом экране примера выбирается значение UpdateBehaviour — модель обновления конфигурации. Смена модели потребует перезапуска приложения.

Работа с конфигурацией

После выбора модели обновления доступны:

• createRemoteConfig — создание клиента Remote Config;
• init — инициализация клиента;
• getRemoteConfig — получение и отображение конфигурации;
• getTypedValues — типизированное чтение значений по ключу;
• setAccount / setLanguage — динамически передаваемые параметры для синхронизации конфигурации.

API

createRemoteConfig

createRemoteConfig(
  appId: string,
  updateInterval: number,
  updateBehaviour: UpdateBehaviour,
  params?: RemoteConfigClientParams
): void

Создает нативный RemoteConfigClient. Метод синхронный (не возвращает Promise) и должен быть вызван до использования остальных методов — иначе они завершатся ошибкой RemoteConfigClientNotCreated.

• Повторные вызовы игнорируются.
• После перезагрузки JS-бандла (RN reload) нативный клиент не пересоздается, а переиспользуется.
• updateInterval задается в минутах и используется только для моделей обновления DEFAULT и SNAPSHOT.

RemoteConfigClientParams

Дополнительные параметры запроса конфигурации. Все поля опциональны.

UpdateBehaviour

Модель обновления конфигурации. Подробнее — в документации.

init

init(): Promise<boolean>

Инициализирует клиент. При успехе resolves с true, при неудаче rejects с ошибкой. Завершение инициализации также можно отследить через событие INIT_COMPLETE.

getRemoteConfig

getRemoteConfig(): Promise<Record<string, string>>

Возвращает всю конфигурацию как объект «ключ — значение». Все значения — строки; для чтения с приведением типа используйте типизированные геттеры.

getShortSegments

getShortSegments(): Promise<string | null>

Возвращает идентификаторы коротких сегментов или null, если они отсутствуют.

Типизированные геттеры

Геттеры читают последнюю полученную конфигурацию. Если конфигурация еще не была загружена, геттер сначала выполнит ее загрузку, а затем вернет значение.

Если ключа нет в конфигурации, вызов завершается ошибкой RemoteConfigCastException вида error getting the value by key: (key) as String. Если значение не приводится к запрошенному типу (например, getBoolean для значения "Default value"), ошибка содержит значение: error getting the value by key: (key) as Boolean: (value).

setAccount / setLanguage

setAccount(account: string): void
setLanguage(language: string): void

Динамически передаваемые параметры — применяются ко всем последующим запросам конфигурации. На iOS Swift SDK поддерживает динамическое изменение только account; language применяется, если задан до createRemoteConfig.

Управление кэшем (iOS)

getKeys(): Promise<string[]>
getObject(key: string): Promise<string | boolean | number | null>
getCacheModificationDate(): Promise<number | null>
removeCache(): Promise<void>

Эти методы соответствуют дополнительным API Swift SDK. getCacheModificationDate возвращает Unix timestamp в миллисекундах.

События

Подписка через remoteConfigEventEmitter. Полезная нагрузка каждого события — объект { callback: string } (строковое представление результата или исключения).

На iOS SDK генерирует события INIT_COMPLETE, FIRST_LOAD_COMPLETE, PERSISTENT_STORAGE_UPDATED и REMOTE_CONFIG_NETWORK_REQUEST_FAILURE.

import { RemoteConfigEvents, remoteConfigEventEmitter } from 'react-native-rustore-remote-config';

const subscription = remoteConfigEventEmitter.addListener(
  RemoteConfigEvents.MEMORY_CACHE_UPDATED,
  (event) => console.log(event.callback)
);

// Не забудьте отписаться
subscription.remove();

Обработка ошибок

Все асинхронные методы при ошибке отклоняют Promise:

• code — имя класса исключения SDK (RemoteConfigNetworkException, RemoteConfigClientNotCreated, RemoteConfigCastException, FailedToReceiveRemoteConfig и др.);
• message — сообщение исключения. Для сетевых ошибок дополнительно указывается HTTP-код: response with error from https://client-api-m.remote-config.rustore.ru/api/get (HTTP 400).

Типичные ошибки:

Сборка примера приложения

Вы можете ознакомиться с демонстрационным приложением содержащим представление работы всех методов sdk:

• README
• example

Для iOS используйте Ruby 3.3+ и CocoaPods 1.17:

cd example
bundle install
cd ios
bundle exec pod install

Условия распространения

Данное программное обеспечение, включая исходные коды, бинарные библиотеки и другие файлы распространяется под лицензией MIT. Информация о лицензировании доступна в документе MIT-LICENSE.

Техническая поддержка

Дополнительная помощь и инструкции доступны на странице help.rustore.ru.