SDK Remote Config для Defold (version 1.0.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.

Connecting to project

Build the plugin and install it in your project:

1. Copy the plugin project and example application from the official RuStore repository on GitFlic;

2. Open the Android project from the extension_libraries folder in your IDE.

3. Use the gradle assemble command to assemble the project.

   If the build is successful, files will be created in remoteconfig_example / extension_rustore_remoteconfig / lib / android and remoteconfig_example / extension_rustore_core / lib / android folders:

   • RuStoreDefoldRemoteConfig.jar;
   • RuStoreDefoldCore.jar.

4. Copy and save the folders remoteconfig_example / extension_rustore_remoteconfig, remoteconfig_example / extension_rustore_core, remoteconfig_example / extension_rustore_application to the root of your project.

5. In your project manifest file, replace the android.support.multidex.MultiDexApplication class with ru.rustore.defold.remoteconfig.DefoldRemoteConfigApplication.

Модификация манифеста

<application
        {{#has-icons?}}
        android:icon="@drawable/icon"
        {{/has-icons?}}
        android:label="{{project.title}}" android:hasCode="true"
        android:name="ru.rustore.defold.remoteconfig.DefoldRemoteConfigApplication"
        android:enableOnBackInvokedCallback="true"
        android:debuggable="{{android.debuggable}}">

</application>

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.

Initialization

RemoteConfigClient creation

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

Пример DefoldRemoteConfigApplication.java

package ru.rustore.defold.remoteconfig;

import android.app.Application;
import android.content.Context;
import ru.rustore.defold.remoteconfig.model.DefoldUpdateBehaviour;
import ru.rustore.defold.remoteconfig.RuStoreDefolRemoteConfigBuilder;

public class DefoldRemoteConfigApplication extends Application {
	public final String APP_ID = "a83c91d3-21b4-4891-841e-0ed0fc39a562";
	public final int UPDATE_TIME = 15;
	public final DefoldUpdateBehaviour UPDATE_BEHAVIOUR = DefoldUpdateBehaviour.Actual;
	
	@Override
	public void onCreate() {
		super.onCreate();

		RuStoreDefoldRemoteConfigBuilder.INSTANCE.init(APP_ID, UPDATE_BEHAVIOUR, UPDATE_TIME, null, null, getApplicationContext());
	}
}

• APP_ID — remote config unique ID. Available in RuStore Console on the Remote Configuration Parameters Creation page;
• UPDATE_TIME — update timer interval in minutes;
• UPDATE_BEHAVIOUR — parameter that defines SDK behaviour. See Difference in UpdateBehaviour values.

To replace the Application class with DefoldRemoteConfigApplication in your project's manifest file, change the android:name attribute in the application tag:

Модификация манифеста

<application
        {{#has-icons?}}
        android:icon="@drawable/icon"
        {{/has-icons?}}
        android:label="{{project.title}}" android:hasCode="true"
        android:name="ru.rustore.defold.remoteconfig.DefoldRemoteConfigApplication"
        android:enableOnBackInvokedCallback="true"
        android:debuggable="{{android.debuggable}}">

</application>

UpdateBehaviour

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

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.

RemoteConfigClientBuilder optional parameters

You can set optional initialisation parameters via RemoteConfigParameters interface.

Интерфейс RemoteConfigParameters

package ru.rustore.defold.remoteconfig.model;

public interface RemoteConfigParameters {
    String getAppBuild();
    String getAppVersion();
    String getDeviceId();
    String getDeviceModel();
    String getEnvironment();
    String getOsVersion();
}

The Account and Language parameters are available for dynamic transfer via setAccount and setLanguage methods, respectively: The setAccount and setLanguage methods can be called at any time.

Инициализация с опциональными параметрами

import ru.rustore.defold.remoteconfig.model.DefoldUpdateBehaviour;
import ru.rustore.defold.remoteconfig.RuStoreDefoldRemoteConfigBuilder;

public final String APP_ID = "a83c91d3-21b4-4891-841e-0ed0fc39a562";
public final int UPDATE_TIME = 15;
public final DefoldUpdateBehaviour UPDATE_BEHAVIOUR = DefoldUpdateBehaviour.Actual;

public final String ACCOUNT = "MyAccount";
public final String LANGUAGE = "ru";

RemoteConfigClientParametersImpl parameters;

/* Your initialisation of parameters */

RuStoreDefoldRemoteConfigBuilder.INSTANCE.setAccount(ACCOUNT);
RuStoreDefoldRemoteConfigBuilder.INSTANCE.setLanguage(LANGUAGE);
RuStoreDefoldRemoteConfigBuilder.INSTANCE.init(APP_ID, UPDATE_BEHAVIOUR, UPDATE_TIME, parameters, null, getApplicationContext());

You can get the current dynamically set parameters via getАccount and getLanguage methods:

Вызов методов getАccount и getLanguage

String account = RuStoreDefoldRemoteConfigBuilder.INSTANCE.getAccount();
String language = RuStoreDefoldRemoteConfigBuilder.INSTANCE.getLanguage();

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.

Initialization in Lua

Plug-in initialisation is performed automatically when the Defold plug-in system is started. No additional calls to initialising methods are required.

Dynamic parameters

For further synchronisation set-up, it supports dynamic parameter transfer to the server.

The Account and Language parameters are available for dynamic transfer via setAccount and setLanguage methods, respectively:

rustoreremoteconfig.set_account("MyAccount")
rustoreremoteconfig.set_language("ru")

You can get the current parameters via get_account and get_language methods:

local account = rustoreremoteconfig.get_account()
local language = rustoreremoteconfig.get_language()

SDK callbacks

Subscribe to the following events to receive SDK activity callbacks, such as completed initialisation and on-going storage updates.

• rustore_background_job_errors – returns a background operation error.
• rustore_first_load_complete – called once the first load is complete.
• rustore_init_complete - called when initialisation is complete.
• rustore_memory_cache_updated - called when memory cache is changed.
• rustore_persistent_storage_updated - called when on-going storage is changed.
• rustore_remote_config_network_request_failure - called when a Remote Config network request fails.

Use the init_event_listener method to start the listed event listener.

Подписка на события

function init(self)
	rustorecore.connect("rustore_get_remote_config_success", _on_get_remote_config_success)
	rustorecore.connect("rustore_get_remote_config_failure", _on_get_remote_config_failure)
	rustorecore.connect("rustore_rustore_background_job_errors", _on_rustore_background_job_errors)
	rustorecore.connect("rustore_first_load_complete", _on_rustore_first_load_complete)
	rustorecore.connect("rustore_init_complete", _on_rustore_init_complete)
	rustorecore.connect("rustore_memory_cache_updated", _on_rustore_memory_cache_updated)
	rustorecore.connect("rustore_persistent_storage_updated", _on_rustore_persistent_storage_updated)
	rustorecore.connect("rustore_remote_config_network_request_failure", _on_rustore_remote_config_network_request_failure)
	rustoreremoteconfig.init_event_listener()
end

function _on_rustore_background_job_errors(self, channel, value)
	local data = json.decode(value)
end

function _on_rustore_first_load_complete(self, channel, value)
end

function _on_rustore_init_complete(self, channel, value)
end

function _on_rustore_memory_cache_updated(self, channel, value)
end

function _on_rustore_persistent_storage_updated(self, channel, value)
end

function _on_rustore_remote_config_network_request_failure(self, channel, value)
	local data = json.decode(value)
end

The callbacks rustore_background_job_errors and rustore_remote_config_network_request_failure return a JSON string with error information. The error structure is described in Error Handling..

Getting configuration

Call to get_remote_config to obtain configuration.

Subscribe to events once before using this method.

• on_get_remote_config_success;
• on_get_remote_config_success.

Подписка на события

function init(self)
	rustorecore.connect("rustore_get_remote_config_success", _on_get_remote_config_success)
	rustorecore.connect("rustore_get_remote_config_failure", _on_get_remote_config_failure)
end

function _on_get_remote_config_success(self, channel, value)
	local collection = json.decode(value)
	for key, value in pairs(collection.data) do
		local pair = key .. ": " .. value
	end
end

function _on_get_remote_config_failure(self, channel, value)
	local data = json.decode(value)
end

Вызов метода get_remote_config

rustoreremoteconfig.get_remote_config()

The rustore_get_remote_config_success callback returns a JSON string with a set of available parameters as a key-value collection. The collection contains the entire set of keys and values that were transferred from the server. It depends on the dynamically set parameters as well as the parameters specified at initialisation.

The callback rustore_get_remote_config_failure returns a JSON string with error information in the Error parameter. The error structure is described in Error Handling.

Possible errors

It is not recommended to display the error to the user yourself if you get *_failure in response. Showing an error can negatively impact the user experience.

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

function _on_failure(self, channel, value)
    local data = json.decode(value)

    local message = data.detailMessage
end

• detailMessage — error message.

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.