SDK Remote Config for Kotlin (version 0.1.0)

SDK Remote Config is a cloud-based service that lets you change application behaviour and appearance without requiring users to download an application update. The plugin encapsulates configuration request from server, caching, background update. It also offers easy-to-use APIs for data retrieval.

Implementation example

Take a look at example app to learn how to implement SDK Remote Config.

Key features

• Select the most relevant mechanism for updating the configuration.
• Specify the percentage of configuration distribution per audience.
• Pass additional information to build a funnel of a specific configuration. You can even build up configurations for specific users.
• A set of callbacks that can be used for analytics.
• Minimal external dependencies.

Connecting to project

1. Connect a repository:

   build.gradle

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

2. Inject dependencies:

   build.gradle

      dependencies {
       implementation("ru.rustore.sdk:remoteconfig:0.1.0")
   }

Initialization

RemoteConfigClient creation

RemoteConfigClient initialization must be done during Application.onCreate() as by the background sync start the SDK must be already initialized.

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

Using RemoteConfigClientBuilder, you can set optional parameters to get a specific configuration.

caution

Calling RemoteConfigClientBuilder.build() again will cause the RemoteConfigClientAlreadyExist error .

After calling the RemoteConfigClientBuilder.build() method, it creates an instance of RemoteConfigClient and writes a singleton. You can retrieve the created instance as follows:

RemoteConfigClient.instance

RemoteConfigClientNotCreated error will occur if you access it via a static variable before creating it via RemoteConfigClientBuilder.build().

RemoteConfigClientBuilder optional parameters

Parameters	Description
OsVersion	Condition in the configuration tool: Os Version
Allows to compare OsVersion against the value set in the interface. By default OsVersion is not passed, in this case the default configuration will be returned.
DeviceModel	Condition in the configuration tool: Device Model
Allows to compare DeviceModel against the value set in the interface. By default DeviceModel is not passed, in this case the default configuration will be returned.
Language	Condition in the configuration tool: Language
Allows to compare Language against the value set in the interface. By default Language is not passed, In this case the default configuration will be returned.
To pass Language, implement ConfigRequestParameterProvider.
Account	Condition in the configuration tool: Account
Allows to compare account against the value set in the interface. **
Condition in the configuration tool: Account Percentile**
Allows to broadcast the configuration to a specified percent of users based on the account value.
Condition in the configuration tool: Interval Account Percentile Allows to broadcast the configuration to a specified percent of users on a specified day based on the account value.
To pass Account, implement ConfigRequestParameterProvider.
DeviceId	Condition in the configuration tool: DeviceID
Allows to compare DeviceId againste the value set in the interface. **
Condition in the configuration tool: DeviceID Percentile**
Allows to broadcast the configuration to a specified percent of devices based on a on the DeviceId value. **
Condition in the configuration tool: Interval DeviceID Percentile** Allows to broadcast the configuration to a specified percent of devices on a specified day based on the DeviceId value.
AppVersion	Condition in the configuration tool: App Version
Allows to compare AppVersion against the value set in the interface.
Environment	Condition in the configuration tool: App Environment
Allows to compare Environment with the value set in the interface Environment can take the following values: Alpha, Beta, Release.
It is a convenient parameter for testing of the configuration on different app builds.
AppBuild	Condition in the configuration tool: App Build
Allows to compare AppBuild against the value set in the interface.

UpdateBehaviour

UpdateBehaviour— this parameter defines SDK behavior. The default value of the RemoteConfigClientBuilder instance upon creation is UpdateBehaviour.Defaultwith a 15 minute sync interval.

You can set a different SDK behaviour as follows:

remoteConfigClientBuilder.setUpdateBehaviour(UpdateBehaviour.Actual)

Differences in the values of UpdateBehaviour

UpdateBehaviour	Description
Actual	With this type of initialization, **every ** configuration request is made by a request to the server. The ** Actualupdate type ensures the configuration is up to date, however, the speed of the configuration retrieval will depend on the network speed.** This type of initialization cancels the background update.
Default	With this type of initialization, the configuration request is made from the local store that is updated at specified intervals. If it is the first initialization (the local store is empty), a request to the server is made. Theduration of this request depends on the network speed. Configuration access will wait for the initialization to complete. The Default configuration does not guarantee that during the process lifetime configuration retrieval will return the same result, as there can be configuration sync in the background. This initialization type starts background update.
Snapshot	With this type of initialization, the configuration request is made from the local inMemory storage. inMemory-storage will receive the result of the request from the permanent store and save it until the end of the process lifetime. If it is the first initialization (the local store is empty), a request to the server is made. Theduration of this request depends on the network speed. Configuration access will wait for the initialization to complete. The Snapshotconfiguration ensures that during the process lifetime configuration retrieval will return the same result. This initialization type starts background update.

ConfigRequestParameterProvider

ConfigRequestParameterProvider implementation allows to dynamically pass parameters to the server for configuration sync.

Supported parameters: Language and Account.

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

The method needs to be implemented quickly and without lengthy operations. Implementing the long-running getConfigRequestParameter method can lead to long delays in getting the configuration.

caution

The method will be called on RemoteConfig SDK threads.

You can implement a ConfigRequestParameterProvider like this

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

RemoteConfigClientEventListener

RemoteConfigClientEventListener implementation allows to receive callbacks on SDK performance, such as end of initialization and permanent storage updates..

Callback listeners are called on MainThread.

You can add RemoteConfigClientEventListener implementation like this:

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

Example implementation of RemoteConfigEventListener:

class RemoteConfigListenerImpl: RemoteConfigClientEventListener {
    override fun backgroundJobErrors(exception: RemoteConfigException.BackgroundConfigUpdateError) {
        //Returns a background error
    }

    override fun firstLoadComplete() {
        //Called at the end of the first load
    }

    override fun initComplete() {
        //Called at the end of initialisation
    }

    override fun memoryCacheUpdated() {
        //Called when cache memory is changed
    }

    override fun persistentStorageUpdated() {
        //Called when changing permanent storage
    }

    override fun remoteConfigNetworkRequestFailure(throwable: Throwable) {
        //Called in case of Remote Config network request error
    }
}

Initialization RemoteConfigClient

Initialisation of RemoteConfigClient is asynchronous, the result can be monitored via the Task class which returns the init() method, or via the Listener.

remoteConfigClient.init()

Getting configuration

Call to getRemoteConfig() to obtain configuration.

remoteConfigClient.getRemoteConfig()

If the RemoteConfigClient was not previously initialised, the first call to the getRemoteConfig() method will initialise it, which may take some time. It is recommended to initialise the RemoteConfigClient in advance to get the configuration faster.

The getRemoteConfig() method returns RemoteConfig and is executed asynchronously. Task may fail to complete. All errors are described in Error Handling.

On successful completion of Task, RemoteConfig is accessed. This is the current set of data obtained depending on the update policy selected and the initialisation parameters. For some upgrade policies, the configuration retrieval does not depend on the current initialisation parameters, but on the parameters used during background synchronisation.

RemoteConfig class

The RemoteConfig instance is the current set of all data received depending on the update policy selected at initialisation. The instance has the full set of keys transferred from the server depending on the parameters specified at initialisation.

Key availability check

remoteConfig.containsKey("my-key")

The method checks if the key exists in the current RemoteConfig instance.

Retrieving typed data

The RemoteConfig class has methods to retrieve and cast data.

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

Methods may return RemoteConfigCastException if the data type does not match the selected method or there is no value on the key passed.

Background configuration sync

Some types of update policy use the synchronisation of background configuration.

Depending on the chosen update policy, the result of the background synchronisation is that the persistent configuration repository is updated with the latest data.

The minimum allowable interval between background synchronisations is 15 minutes.

caution

For background synchronisation to work correctly, SDK Remote Config must be inilialized in Application.onCreate().

Possible errors

All SDK Remote Config errors inherit from the RemoteConfigException superclass.

Error	Description
BackgroundConfigUpdateError	Displayed if an error occurs during background synchronisation.
FailedToReceiveRemoteConfig	Displayed in case of an error when calling the get configuration method.
RemoteConfigCastException	Displayed if the key data from the RemoteConfig class was retrieved incorrectly. The error may be caused by an impossible type conversion or null key value.
RemoteConfigClientAlreadyExist	Displayed if RemoteConfigClient is recreated within the life of the process.
RemoteConfigClientNotCreated	Displayed if RemoteConfigClient is accessed via the instance static field before RemoteConfigClient is created.
RemoteConfigCommonException	General unexpected error
RemoteConfigNetworkException	Displayed in case of a network error.