Skip to main content

SDK Remote Config для Kotlin (версия 7.0.0)

SDK Remote Config – это облачный сервис, который позволяет изменять поведение и внешний вид вашего приложения, не требуя от пользователей загрузки обновления приложения. Плагин инкапсулирует в себе запрос конфигурации с сервера, кэширование, фоновое обновление. Имеет удобный интерфейс API для получения данных.

Пример реализации​

Ознакомьтесь с приложением-примером, чтобы узнать, как правильно интегрировать SDK Remote Config.

Ключевые особенности​

  • Выбор наиболее удобного механизма обновления конфигурации.
  • Возможность указывать процент распространения конфигурации на аудиторию.
  • Возможность передавать дополнительную информацию для построения воронки конкретной конфигурации. Формировать конфигурацию можно даже для конкретных пользователей.
  • Набор callback, который можно использовать для аналитики.
  • Минимальное количество внешних зависимостей.

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

  1. Подключите репозиторий:

    build.gradle
    repositories {
        maven {
            url = uri("https://artifactory-external.vkpartner.ru/artifactory/maven")
        }
    }

  2. Подключите зависимости:

Преимущества использования BOM-файла для конфигурации.

  1. Единое управление версиями:

    • С BOM вы можете управлять версиями всех зависимостей из одного файла. Это особенно полезно, если вы используете несколько библиотек, которые должны быть совместимы друг с другом.
    • Например, если у вас есть несколько библиотек от RuStore, таких как ru.rustore.sdk:billingclient и ru.rustore.sdk:pushclient, вы можете использовать BOM, чтобы гарантировать, что все они будут совместимы друг с другом.

  2. Упрощение обновлений:

    • Обновление зависимостей становится проще, так как вам нужно изменить версию только в одном месте — в BOM-файле. Это снижает риск пропустить обновление какой-либо зависимости и избежать конфликтов версий.
    • Например, если новая версия BOM-файла содержит обновленные версии всех библиотек, вам достаточно обновить только BOM-файл, а не каждую зависимость по отдельности.

  3. Повышение совместимости:

    • Использование BOM помогает избежать конфликтов версий между различными библиотеками. Это особенно важно, когда библиотеки имеют зависимости друг от друга.
    • Например, если две библиотеки зависят от разных версий одной и той же библиотеки, это может вызвать конфликты. BOM помогает избежать таких ситуаций, гарантируя, что все зависимости совместимы.
build.gradle
dependencies {
    implementation(platform("ru.rustore.sdk:bom:6.0.0"))
    implementation("ru.rustore.sdk:remoteconfig")
}

Инициализация​

Создание RemoteConfigClient​

Инициализация RemoteConfigClient должна происходить в момент Application.onCreate(), так как при запуске фоновой синхронизации SDK должна быть проинициализирована.

 
val remoteConfigClient = RemoteConfigClientBuilder(appId = AppId("your_app_id"), context = applicationContext).build()

Через RemoteConfigClientBuilder можно установить опциональные параметры для получения конкретной конфигурации.

caution

Повторный вызов RemoteConfigClientBuilder.build() вызовет ошибку RemoteConfigClientAlreadyExist .

После вызова метода RemoteConfigClientBuilder.build() создается экземпляр RemoteConfigClient и записывается синглтон. Получить созданный экземпляр можно следующим образом.

RemoteConfigClient.instance

Доступ через статическую переменную до создания через RemoteConfigClientBuilder.build() вызовет ошибку RemoteConfigClientNotCreated.

Опциональные параметры RemoteConfigClientBuilder​

ПараметрОписание
OsVersionУсловие в конфигураторе: Os Version
Позволят сравнивать OsVersion со значением, установленным в интерфейсе. По умолчанию OsVersion не передается, в этом случае возвращается конфиг по умолчанию.
DeviceModelУсловие в конфигураторе: Device Model
Позволят сравнивать DeviceModel со значением, установленным в интерфейсе. По умолчанию DeviceModel не передается, у этом случае возвращается конфиг по умолчанию.
LanguageУсловие в конфигураторе: Language
Позволят сравнивать Language со значением, установленным в интерфейсе. По умолчанию Language не передается, у этом случае возвращается конфиг по умолчанию.
Для передачи Language необходимо реализовать ConfigRequestParameterProvider.
AccountУсловие в конфигураторе: Account
Позволят сравнивать account со значением, установленным в интерфейсе.
Условие в конфигураторе: Account Percentile
Позволят раздавать конфиг по значению account на определенный процент.
Условие в конфигураторе: Interval Account Percentile
Позволят раздавать конфиг по значению account на определенный процент и в определенный день.
Для передачи Account необходимо реализовать ConfigRequestParameterProvider.
DeviceIdУсловие в конфигураторе: DeviceID
Позволят сравнивать DeviceId со значением, установленным в интерфейсе.
Условие в конфигураторе: DeviceID Percentile
Позволят раздавать конфиг по значению DeviceId на определенный процент.
Условие в конфигураторе: Interval DeviceID Percentile
Позволят раздавать конфиг по значению DeviceId на определенный процент и в определенный день.
AppVersionУсловие в конфигураторе: App Version
Позволят сравнивать AppVersion со значением, установленным в интерфейсе.
EnvironmentУсловие в конфигураторе: App Environment
Позволят сравнивать Environment со значением, установленным в интерфейсе
Environment может принимать значения: Alpha, Beta, Release.
Этот параметр удобно использовать для тестирования конфигурации на различных сборках приложения.
AppBuildУсловие в конфигураторе: App Build
Позволят сравнивать AppBuild со значением, установленным в интерфейсе.

UpdateBehaviour​

UpdateBehaviour — это параметр, определяющий поведение SDK. При создании экземпляра RemoteConfigClientBuilder, по умолчанию используется значение UpdateBehaviour.Default с интервалом синхронизации 15 минут.

Установить другое поведение SDK можно следующим образом.

remoteConfigClientBuilder.setUpdateBehaviour(UpdateBehaviour.Actual)

Различия в значениях UpdateBehaviour

UpdateBehaviourОписание

Actual

При инициализации каждый запрос конфигурации выполняется через запрос к серверу.

Значение Actual гарантирует получение самой актуальной конфигурации, но скорость выполнения запроса зависит от скорости сети.

Этот тип инициализации отменяет процесс фонового обновления.

Default

При инициализации запрос конфигурации выполняется из локального постоянного хранилища, которое обновляется в указанный интервал.

Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации.

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

Этот тип инициализации запускает процесс фонового обновления.

Snapshot

При инициализации запрос конфигурации выполняется из локального inMemory-хранилища. inMemory-хранилище заполняется результатом первого запроса из постоянного хранилища и сохраняется в таком виде до конца жизни процесса.

Если инициализация выполняется первый раз и локальное постоянное хранилище пустое, запрос отправляется на сервер. Скорость выполнения запроса зависит от объема данных и скорости сети. Доступ к конфигурации будет ожидать завершения инициализации.

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

Этот тип инициализации запускает процесс фонового обновления.

ConfigRequestParameterProvider​

Реализация ConfigRequestParameterProvider дает возможность динамически передавать параметры на сервер для синхронизации конфигурации.

Поддерживаемый список параметров: Language и Account.

class ConfigRequestParameterProviderImpl : ConfigRequestParameterProvider {
    override fun getConfigRequestParameter(): ConfigRequestParameter =
        ConfigRequestParameter(
            language = Language(Locale.getDefault().language),
            account = Session.id,
        )
}

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

caution

Вызов метода будет происходить на потоках RemoteConfig SDK.

Добавить реализацию ConfigRequestParameterProvider можно следующим образом.

val provider = ConfigRequestParameterProviderImpl()
remoteConfigClientBuilder.setConfigRequestParameterProvider(provider)

RemoteConfigClientEventListener​

Реализация RemoteConfigClientEventListener дает возможность получать обратные вызовы (callback) о работе SDK, такие как завершение инициализации и обновление постоянного хранилища.

Callback слушателя вызываются на MainThread.

Добавить реализацию RemoteConfigClientEventListener можно следующим образом.

val listener = RemoteConfigClientEventListenerImpl()
remoteConfigClientBuilder.setRemoteConfigClientEventListener(listener)

Пример имплементации RemoteConfigEventListener.

class RemoteConfigListenerImpl: RemoteConfigClientEventListener {
    override fun backgroundJobErrors(exception: RemoteConfigException.BackgroundConfigUpdateError) {
        //Возвращает ошибку фоновой работы
    }
 
    override fun firstLoadComplete() {
        //Вызывается при окончании первой загрузки
    }
 
    override fun initComplete() {
        //Вызывается при окончании инциализации
    }
 
    override fun memoryCacheUpdated() {
        //Вызывается при измененияя кэша в памяти
    }
 
    override fun persistentStorageUpdated() {
        //Вызывается при изменении постоянного хранилища
    }
 
    override fun remoteConfigNetworkRequestFailure(throwable: Throwable) {
        //Вызывается при ошибке сетевого запроса Remote Сonfig
    }
}

Инициализация RemoteConfigClient​

Инициализация RemoteConfigClient выполняется асинхронно, через класс Task, который возвращает метод init(), или через слушатель.

remoteConfigClient.init()

Получение конфигурации​

Получение конфигурации происходит через вызов метода getRemoteConfig().

 
remoteConfigClient.getRemoteConfig()

Если RemoteConfigClient не был проинициализирован ранее, при первом вызове метода getRemoteConfig() произойдет инициализация, что может занять некоторое время. Для более быстрого получения конфигурации, инициализацию RemoteConfigClient стоит производить заранее.

Метод getRemoteConfig() возвращает RemoteConfig и выполняется асинхронно. Task может завершиться неудачно. Все ошибки описаны в разделе Возможные ошибки.

После успешного завершения Task, появится доступ к RemoteConfig, это текущий набор всех данных, полученных в зависимости от выбранной политики обновления и параметров при инициализации. При некоторых политиках обновления, получение конфигурации будет зависеть не от текущих параметров инициализации, а от параметров, которые использовались во время фоновой синхронизации.

Класс RemoteConfig​

Экземпляр RemoteConfig — это текущий набор всех данных, полученных в зависимости от выбранной политики обновления при инициализации, экземпляр имеет весь набор ключей, которые были переданы с сервера в зависимости от параметров, указанных при инициализации.

Проверка доступности ключа​

remoteConfig.containsKey("my-key")

Метод проверяет наличие ключа в текущем экземпляре RemoteConfig.

Получение типизированных данных​

Класс RemoteConfig имеет методы получения данных и приведения его к определенным типам:

  • getBoolean(key: String): Boolean;
  • getInt(key: String): Int;
  • getLong(key: String): Long;
  • getString(key: String): String;
  • getDouble(key: String): Double;
  • getFloat(key: String): Float.

Методы могут вернуть ошибку RemoteConfigCastException, если тип данных не соответствует выбранному методу или отсутствует значение по передаваемому ключу.

Фоновая синхронизация конфигурации​

Фоновая синхронизация конфигурации используется при некоторых типах политики обновления.

Результатом фоновой синхронизации конфигурации является обновление постоянного хранилища конфигураций актуальными данными для последующего использования в зависимости от выбранной политики обновления.

Минимальный допустимый интервал между фоновыми синхронизациями составляет 15 минут.

caution

Для корректной работы фоновой синхронизации, инициализация SDK Remote Config должна происходить в методе Application.onCreate().

Возможные ошибки​

Все ошибки SDK Remote Config наследуются от суперкласса RemoteConfigException.

ОшибкаОписание
BackgroundConfigUpdateErrorПоявляется при ошибке в работе фоновой синхронизации.
FailedToReceiveRemoteConfigПоявляется в случае ошибки при вызове метода получения конфигурации.
RemoteConfigCastExceptionПоявляется в случае некорректного получения данных по ключу из класса RemoteConfig. Ошибка может быть связана с невозможностью приведения к типу, либо значение по передаваемому ключу отсутствует.
RemoteConfigClientAlreadyExistПоявляется в случае повторного создания RemoteConfigClient в рамках жизни процесса.
RemoteConfigClientNotCreatedПоявляется в случае доступа к RemoteConfigClient через статическое поле instance до создания RemoteConfigClient.
RemoteConfigCommonExceptionОбщая непредвиденная ошибка.
RemoteConfigNetworkExceptionПоявляется при сетевой ошибке.