Remote configuration SDK integration

This functionality is in Beta mode. If you would like to participate, let us know by using the Contact Us form or reach out to our Customer Success team directly within the platform. We will also greatly appreciate your feedback. Please add REMOTE CONFIGS when submitting your request.

Prerequisite:

Currently remote configs are available only for SDK version 2.6.0 (Android & iOS) and Unity 3.10.0 and higher.

How to configure remote configuration in devtodev interface:

Working with remote configuration in devtodev

What is a remote configuration

Remote configuration (RC or remote config) is a tool that allows you to remotely change the appearance or logic of the app without publishing a new version of the app.

With the help of remote configs you can:

1. Change app behavior for all users or just for a specific audience.

2. Conduct A/B tests to compare different configurations on the same audience and find the best performing one.

Please note that in order for remote configuration mechanism to work, you will need to prepare all of the possible changes beforehand. This includes the possible changes in app logic and interface.

In devtodev, A/B test is considered a specific case of a remote configuration.

Integration plan in short

This is a short description of how the RC integration will work.

1. In your app, you will need to declare a set of variables and set default values for these variables. We’ll call these variables Parameters.

2. Use these parameters in your app according to your realisation of the app logic. Note that parameter value can change and it will affect the app behavior the way it’s determined by your business logic. There is a special method to get the current parameter value.

3. Integrate a listener method that will notify you if at least one parameter value has changed. Add a reaction logic to this notification based on our proposed strategies.

4. Initialize devtodev SDK with a specific method to activate the remote configs.

How remote configs work

1. In the devtodev interface you can change parameter values for a specific audience (Remote Configuration) or create an A/B test (A/B Testing).

2. During initialization, devtodev SDK makes a request to the server and receives a list of parameters and their new values according to the configuration. If you also conduct an A/B test at the same time, the SDK will receive a set of conditions to enter the test, a test group and parameter values.

3. If the SDK receives a new value for at least one of the parameters in current configuration, it will notify you. This change can be triggered by a remote config or when the user enters an A/B test. The SDK will give you a list of parameter changes and triggers for each change source. Using the update notification and list of changes, select one of the strateges to react.

4. When you receive a notification about parameter changes, you can activate (apply) the values according to your app logic. You will be able to use the updated parameter values until you receive and apply a new configuration. You can check for changes right after devtodev SDK initialization.

Attention! If the user enters an A/B test, the SDK will mark of their events with an A/B test group regardless whether you have activated the proposed parameter changes. We recommend activating and applying these changes as soon as possible!

Parameter value priority

The parameter always has a defined default value. This value can be changed if you set a new value using the remote configuration.

If a user enters an A/B test, they will receive parameter values accoring to their test group configuration.

Parameter values received during an A/B test rewrite the default values and previously set values from the remote config. These test values cannot be changed until you finish the experiment (A/B test value has the highest priority).

The priority order for parameter value source is the following:

1. Top priority – A/B test parameter value.

2. Remote config value from devtodev server.

3. Least priority – Default value defined in the application code.

Integration

Setting up default parameter values

Set the variable (parameter) values in the DTDRemoteConfig class using the DTDRemoteConfig.defaults property.

The SDK does not change any values in the defaults property.

After setting DTDRemoteConfig.defaults, you will be able to get parameter values using the DTDRemoteConfig.config property.

Always use the config property to get up-to-date parameter value configurations.

Waiting for an A/B test group

When you start an A/B test in devtodev, the SDK checks the conditions to enter the experiment. If the user is suitable for the experiment, the SDK will wait for a test group from devtodev server to enter the experiment.

The default wait time groupDefinitionWaiting is 10 seconds.

You can reduce or extend the wait time value.

For example:

 DTDRemoteConfig.groupDefinitionWaiting = 2

In this case, the SDK will be waiting for a group from the server no longer than two seconds. After that, the experiment will be cancelled and the test configuration will be impossible to activate. During the following SDK initialization (application re-start) the user will be able to enter the experiment again.

You can set the DTDRemoteConfig.groupDefinitionWaiting value only before SDK initialization!

Remote config initialization

In order to use the remote configs or A/B tests, use the DTDAnalytics.initializeWithRemoteConfig to initialize devtodev SDK.

Migrating from previous SDK versions

• If you have previously worked with devtodev A/B tests, you will need to change the DTDAnalytics.initializeWithAbTest method to DTDAnalytics.initializeWithRemoteConfig for SDK initialization. The initializeWithAbTest method is not supported in SDK 2.6.0 (Unity 3.10.0) and higher.

• The DTDRemoteConfigListener currently implements only one method – onChanged(update: DTDRemoteConfigUpdate) with a different signature. You will need to remove the onReceived(result: DTDRemoteConfigReceiveResult) and onPrepareToChange() methods, since the updated A/B test mechanism does not utilize these methods.

Unlike the previous SDK versions, the onChanged(update: DTDRemoteConfigUpdate) method will be called only when there is a change in the remote configuration or A/B test.

When you migrate to SDK version 2.6.0 (Unity 3.10.0) and higher, during the first SDK initialization the onChanged(update: DTDRemoteConfigUpdate) method will be called automatically if the device is participating in an active A/B test.

The method will notify you the config with A/B test variables is ready. Since the device is already participating in the test, the latest configuration is already available in DTDRemoteConfig.config.

You must call the applyConfig method to apply and use the test values.

The following SDK launches will not call the onChanged(update: DTDRemoteConfigUpdate) method automatically.

Using the onChanged method with remote configuration

1. devtodev server sends new or updated parameter configuration to the SDK.

2. The onChanged() method is called.

Using the onChanged method with A/B test

1. The SDK found and activated (entered) a suitable experiment.

2. The onChanged() method is called.

3. When the experiment is finished and parameter values are different from the experiment configuration, the onChanged() method is called.

Applying the config

To accept and activate the remote configuration, call the DTDRemoteConfig.applyConfig() method.

When you apply the new configuration, the default, remote config and test group values will intersect according to their priority order. After that the new configuration values will be available in the DTDRemoteConfig.config property.

To decline a remote config or A/B test participation, call the DTDRemoteConfig.resetConfig() method. After calling this method, the parameter values will be set to defaults.

The SDK stores the received configuration until the user deletes the application from the device. Or until you call resetConfig to reset all the active and unapplied configs to defaults.

Strategies for config application

The onChanged(update: DTDRemoteConfigUpdate) method notifies the developer that the configuration has changed. The DTDRemoteConfigUpdate object stores the list of updated keys.

Besides the key-value pairs, you can check the how a parameter was updated (remote config or A/B test) using the DTDRemoteChangeSource. Knowing the source of change can be useful to select the best strategy to apply the configuration in different cases at the right moment.

1. Activating config during the current session. In case you need to get the results of parameter configuration change during the same session, call the DTDRemoteConfig.applyConfig() method at any convenient time after the onChanged was triggered. The onChanged is triggered when the devtodev server sends a new or updated config to the device.

2. A/B testing. When you are working with A/B tests, we recommend calling the DTDRemoteConfig.applyConfig() method as soon as possible because the user will be assigned a test group immediately after the onChanged was triggered.

3. Activating config in a different session. If you do not have a config that you need to activate during the current session, you can call the DTDRemoteConfig.applyConfig() method at any time during the following SDK launches instead of applying config right after onChanged is triggered.

External interfaces description

DTDRemoteConfig

The SDK provides threads synchronization when working with this class.

Property	Description
groupDefinitionWaiting:Double	Wait time for A/B test configuration. Default value - 10.0 (measured in seconds).
defaults: Map<String, Any>	Paramateres and their default values.
config: DTDRemoteConfigCollection	A collection of current parameters and their values for A/B tests. It allows access to the configuration values by using the subscripting syntaxis.

Method	Description
applyConfig()	Applies the remote config or A/B test configuration. After the call, the new config is ready for use in the app.
resetConfig()	Resets the config values to defaults.
cacheTestExperiment()	A debug method for saving a test experiment after restarting the application.

DTDRemoteConfigCollection

Wrapper for collecting remote parameters. Enables access to configuration values by using subscripting syntax.

DTDRemoteConfigValue

Wrapper for working with remote configuration variables (parameters). It presents a method for data source identification, as well as methods for presenting values in the form of various data types.

Type	Description
DTDRemoteConfigSource.Undefined	The variable could not be found in the default or the remote configuration.
DTDRemoteConfigSource.Defaults	The variable is set by default.
DTDRemoteConfigSource.Remote	The variable is set by remote config.
DTDRemoteConfigSource.AbTest	The variable is set by the test group.

Property	Type	Description
stringValue	String?	Gets the value as a optional string.
floatValue	Float	Gets the value as a Float.
doubleValue	Double	Gets the value as a Double.
int32Value	Int32	Gets the value as a Int32.
int64Value	Int32	Gets the value as a Int32.
integerValue	Int	Gets the value as a Int.
boolValue	Bool	Gets the value as a Bool.

DTDRemoteConfigListener

Implements the method that reports about remote configuration and A/B test update.

Method	Description
onChanged(update: DTDRemoteConfigUpdate)	Notifies the developer that the configuration has changed with a list of updated variables.

DTDRemoteConfigUpdate

Fields	Description
val keys: List<DTDRemoteConfigChangeKey>	Contains a list of updated keys.

DTDRemoteConfigChangeKey

The source of the key update.

Fields	Description
val key: String val source: DTDRemoteConfigSource	Contains the key name and update source.

List of errors

This messages may be useful for debugging.

Error message	Description
[A/B-Test Module] The Server refused to conduct the experiment.	devtodev server refused to send the experiment configuration.
[A/B-Test Module] Offer from devtodev not received within the allotted N seconds.	The backend offer is returned after wait time is over e.g. due to a bad internet connection.
[A/B-Test Module] Offer from devtodev not received within the allotted N seconds.	The SDK was unable to receive an offer from the backend within N seconds e.g, due to a bad internet connection or network problems.

Remote configuration examples

Example 1

In this exapmle we set the default values for variables (parameters) title, buttonText, tutorial before devtodev SDK initialization.

After the onChanged method is triggered, we call DTDRemoteConfig.applyConfig() and apply the received parameter values without any conditions. All inside the onChanged method.

You can get the parameter values in any other place in the app in addition to the onChanged method.

Android (Kotlin)

// Initialization of defaults
DTDRemoteConfig.defaults = mapOf(
   "title" to "local title data",
   "buttonText" to "local button data",
   "tutorial" to "local tutorial data"
)
// DTDAnalytics Initialization
DTDAnalytics.initializeWithRemoteConfig(
    this.appKey, config, context.applicationContext,
    object : DTDRemoteConfigListener {
        // onChanged implementation
        override fun onChanged(update: DTDRemoteConfigUpdate) {
           // Apply config data
            DTDRemoteConfig.applyConfig()
            // Take data from config
            val titleValue = DTDRemoteConfig.config["title"].stringValue
            val buttonTextValue = DTDRemoteConfig.config["buttonText"].stringValue
            val tutorialValue = DTDRemoteConfig.config["tutorial"].stringValue
            Log.d("[remoteConfig]", "title after applyConfig: $titleValue")
            Log.d("[remoteConfig]", "buttonTextValue after applyConfig: $buttonTextValue")
            Log.d("[remoteConfiga]", "tutorialValue after applyConfig: $tutorialValue")
        }
    }
)

Unity

 public class RemoteConfigListenerExample : IDTDRemoteConfigListener
    {
        public void OnChanged(Dictionary<string, DTDRemoteConfigSource> updatedKeys)
        {
            DTDRemoteConfig.ApplyConfig();
            // Take data from config

            var titleValue = DTDRemoteConfig.Config["title"].StringValue();
            var buttonTextValue = DTDRemoteConfig.Config["buttonText"].StringValue();
            var tutorialValue = DTDRemoteConfig.Config["tutorial"].StringValue();
            Debug.Log($"[remoteConfig] title after applyConfig: {titleValue}");
            Debug.Log($"[remoteConfig] buttonTextValue after applyConfig: {buttonTextValue}");
            Debug.Log($"[remoteConfiga] tutorialValue after applyConfig: {tutorialValue}");
        }
    }

    public class RemoteConfigExample
    {
        public void InitializeDevToDev(string appKey, DTDAnalyticsConfiguration analyticsConfiguration)
        {
            DTDRemoteConfig.Defaults = new Dictionary<string, object>
            {
                { "title", "local title data" },
                { "buttonText", "local button data" },
                { "tutorial", "local tutorial data" }
            };
            DTDAnalytics.InitializeWithRemoteConfig(appKey, analyticsConfiguration,
                new RemoteConfigListenerExample());
        }
    }

Example 2

In this exapmle we set the default values for variables (parameters) title, buttonText, tutorial before devtodev SDK initialization.

After the onChanged method is triggered, we check if there are any keys that were updated for the A/B test.

• If there is such key, the user will immediately enter the A/B test and get the experiment configuration.

• If no key was updated for the A/B test, this means the SDK received only new remote configs without A/B test configuration and you do not need to call DTDRemoteConfig.applyConfig() right away.

  • You can apply the remote config at any convenient moment even after the app restarts.

We have added a DTDRemoteConfig.applyConfig() call after the SDK initialization. Since the onChanged was triggered in the previous app launch, we have the up-to-date remote config values on the device.

Android (Kotlin)

// Initialization of defaults
DTDRemoteConfig.defaults = mapOf(
   "title" to "local title data",
   "buttonText" to "local button data",
   "tutorial" to "local tutorial data"
)
// DTDAnalytics Initialization
DTDAnalytics.initializeWithRemoteConfig(
    this.appKey, config, context.applicationContext,
    object : DTDRemoteConfigListener {
        // onChanged implementation
        override fun onChanged(update: DTDRemoteConfigUpdate) {
            // Check if there are a/b test keys
            val abTestKey = update.keys.firstOrNull { it.source == DTDRemoteConfigSource.AbTest }?.key
                if (abTestKey != null) {
                    //Apply config data
                    DTDRemoteConfig.applyConfig()

                    // Take data from config
                    val titleValue = DTDRemoteConfig.config["title"].stringValue
                    val buttonTextValue = DTDRemoteConfig.config["buttonText"].stringValue
                    val tutorialValue = DTDRemoteConfig.config["tutorial"].stringValue
                    Log.d("[remoteConfig]", "title after applyConfig with a/b test: $titleValue")
                    Log.d("[remoteConfig]", "buttonTextValue after applyConfig a/b test: $buttonTextValue")
                    Log.d("[remoteConfig]", "tutorialValue after applyConfig a/b test: $tutorialValue")
                }
            }
        }
    }
)
//Apply config data
DTDRemoteConfig.applyConfig()
// Take data from config
val titleValue = DTDRemoteConfig.config["title"].stringValue
val buttonTextValue = DTDRemoteConfig.config["buttonText"].stringValue
val tutorialValue = DTDRemoteConfig.config["tutorial"].stringValue
Log.d("[remoteConfig]", "title after applyConfig: $titleValue")
Log.d("[remoteConfig]", "buttonTextValue after applyConfig: $buttonTextValue")
Log.d("[remoteConfig]", "tutorialValue after applyConfig: $tutorialValue")

Unity

public class RemoteConfigListenerExample : IDTDRemoteConfigListener
{
    public void OnChanged(Dictionary<string, DTDRemoteConfigSource> updatedKeys)
    {
        DTDRemoteConfig.ApplyConfig();
        // Take data from config
        var hasAbTestKey = updatedKeys.Any(x => x.Value == DTDRemoteConfigSource.ABTest);
        if (hasAbTestKey)
        {
            var titleValue = DTDRemoteConfig.Config["title"].StringValue();
            var buttonTextValue = DTDRemoteConfig.Config["buttonText"].StringValue();
            var tutorialValue = DTDRemoteConfig.Config["tutorial"].StringValue();
            Debug.Log($"[remoteConfig] title after applyConfig: {titleValue}");
            Debug.Log($"[remoteConfig] buttonTextValue after applyConfig: {buttonTextValue}");
            Debug.Log($"[remoteConfiga] tutorialValue after applyConfig: {tutorialValue}");
        }
    }
}

public class RemoteConfigExample
{
    public void InitializeDevToDev(string appKey, DTDAnalyticsConfiguration analyticsConfiguration)
    {
        DTDRemoteConfig.Defaults = new Dictionary<string, object>
        {
            { "title", "local title data" },
            { "buttonText", "local button data" },
            { "tutorial", "local tutorial data" }
        };
        DTDAnalytics.InitializeWithRemoteConfig(appKey, analyticsConfiguration,
            new RemoteConfigListenerExample());
    }
}