Create Remote Config

The Remote Config feature helps you change your onboarding flows, paywall UI, or pricing settings without additional app releases. Moreover, it enables you to rapidly iterate with your monetization experiments

1. Select your app context to configure

As a first step, name your remote configuration and select a context (part of your application) you’d like to manage remotely. Examples of app contexts you may configure with us:

main_paywall: to set up settings for different user segments for your main paywall.
main_paywall_products: to manage only products remotely.
onboarding: to set up the entire user onboarding journey.
onboarding_step_2: to configure only specific steps of the user onboarding flow.
[your_key]: to set up any part of your user’s monetization experience.

Creating a configuration: name and context key

2. Add attributes for your configuration

Qonversion Remote Config provides you with flexible in-app values using which you can set up any behavior and appearance of your app. The core of these in-app values is a plain JSON file consisting of key-value data. We support the following data types:

String.
- Use this option to validate pricing, communication, or visual hypothesis.
- Examples: native.subs.full.v4.w.8.99.trial.7d, Unlock Fast and Secure Browsing, #3076FF, etc.
Number.
- Use this option, for example, to show only a subset of your onboarding screens.
- Examples: 2, 5, 23, etc.
Boolean.
- Use this option to turn on or off some features.
- Examples: true, false
Json.
- Use this option to validate advanced changes in your app’s behavior.
- Examples: {"banner_text": "Choose your plan", "product_top": "native.subs.full.v4.w.8.99.trial.7d", "product_bottom": "subs.month.17.99", "skip_onboarding": true}.

Adding a JSON payload to a configuration

3. Integrate changes into your app

Configuration source

Qonversion Remote Configs and Experiments share single methods to get configurations. You can distinguish the source of the result received by looking at the source field. Learn more about fields available.

To receive the configuration with the Context key set, call the following Qonversion remoteConfig method.

Qonversion.shared().remoteConfig(contextKey: "my_context_key") { remoteConfig, error in
    // Use remoteConfig here
}

[[Qonversion sharedInstance] remoteConfig:@"my_context_key" completion:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
    // Use remoteConfig here
}];

Qonversion.shared.remoteConfig("my_context_key", object : QonversionRemoteConfigCallback {
    override fun onSuccess(remoteConfig: QRemoteConfig) {
        // Use remoteConfig here
    }

    override fun onError(error: QonversionError) {
        // Handle error here
    }
})

Qonversion.getSharedInstance().remoteConfig("my_context_key", new QonversionRemoteConfigCallback() {
    @Override
    public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
        // Use remoteConfig here
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // Handle error here
    }
});

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');

final remoteConfig = await Qonversion.getSharedInstance().remoteConfig(contextKey: "my_context_key");

Qonversion.GetSharedInstance().RemoteConfig("my_context_key", (remoteConfig, error) =>
{
    // Use remoteConfig here
});

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig('my_context_key');

In case you’re using configurations with empty Context key, call the same method with no arguments added:

Qonversion.shared().remoteConfig { remoteConfig, error in
    // Use remoteConfig here
}

[[Qonversion sharedInstance] remoteConfig:^(QONRemoteConfig * _Nullable remoteConfig, NSError * _Nullable error) {
    // Use remoteConfig here
}];

Qonversion.shared.remoteConfig(object : QonversionRemoteConfigCallback {
    override fun onSuccess(remoteConfig: QRemoteConfig) {
        // Use remoteConfig here
    }

    override fun onError(error: QonversionError) {
        // Handle error here
    }
})

Qonversion.getSharedInstance().remoteConfig(new QonversionRemoteConfigCallback() {
    @Override
    public void onSuccess(@NonNull QRemoteConfig remoteConfig) {
        // Use remoteConfig here
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // Handle error here
    }
});

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();

final remoteConfig = await Qonversion.getSharedInstance().remoteConfig();

Qonversion.GetSharedInstance().RemoteConfig((remoteConfig, error) =>
{
    // Use remoteConfig here
});

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();

const remoteConfig = await Qonversion.getSharedInstance().remoteConfig();

If necessary, you can also request a list of remote configs for all the context keys, including the empty one.

Qonversion.shared().remoteConfigList { remoteConfigList, error in
  // Use remoteConfigList here
}

[[Qonversion sharedInstance] remoteConfigList:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
  // Use remoteConfigList here
}]

Qonversion.shared.remoteConfigList(object : QonversionRemoteConfigListCallback {
    override fun onSuccess(remoteConfigList: QRemoteConfigList) {
        // Use remoteConfigList here
    }

    override fun onError(error: QonversionError) {
        // Handle error here
    }
})

Qonversion.getSharedInstance().remoteConfigList(new QonversionRemoteConfigListCallback() {
    @Override
    public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
      // Use remoteConfigList here
    }

    @Override
    public void onError(@NonNull QonversionError error) {
      // Handle error here
    }
});

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();

final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();

Qonversion.GetSharedInstance().RemoteConfigList((remoteConfigList, error) =>
{
    // Use remoteConfigList here
});

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigList();

If you need remote configs for a specific set of context keys, just use the following method.

Qonversion.shared().remoteConfigList(
  contextKeys: ["my_context_key", "another_context_key"],
  includeEmptyContextKey: true // to include remote config without context key
) { remoteConfigList, error in
  // Use remoteConfigList here
}

[[Qonversion sharedInstance] remoteConfigList:@[@"my_context_key", @"another_context_key"]
                       includeEmptyContextKey:YES // to include remote config without context key
 																	 completion:^(QONRemoteConfigList * _Nullable remoteConfigList, NSError * _Nullable error) {
  // Use remoteConfigList here
}

Qonversion.shared.remoteConfigList(
    listOf("my_context_key", "another_context_key"),
    true, // to include remote config without context key
    object : QonversionRemoteConfigListCallback {
        override fun onSuccess(remoteConfigList: QRemoteConfigList) {
            // Use remoteConfigList here
        }

        override fun onError(error: QonversionError) {
            // Handle error here
        }
	  }
)

Qonversion.getSharedInstance().remoteConfigList(
    Arrays.asList("my_context_key", "another_context_key"),
    true, // to include remote config without context key
    new QonversionRemoteConfigListCallback() {
        @Override
        public void onSuccess(@NonNull QRemoteConfigList remoteConfigList) {
            // Use remoteConfigList here
        }

        @Override
        public void onError(@NonNull QonversionError error) {
            // Handle error here
        }
		}
);

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
  ['my_context_key', 'another_context_key'],
  true // to include remote config without context key
);

final remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
  ["my_context_key", "another_context_key"],
  true // to include remote config without context key
);

Qonversion.GetSharedInstance().RemoteConfigList(
  new string[] {"my_context_key", "another_context_key"},
  true, // to include remote config without context key
  (remoteConfigList, error) =>
{
    // Use remoteConfigList here
});

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
  ['my_context_key', 'another_context_key'],
  true // to include remote config without context key
);

const remoteConfigList = await Qonversion.getSharedInstance().remoteConfigListForContextKeys(
  ['my_context_key', 'another_context_key'],
  true // to include remote config without context key
);

`RemoteConfigList` fields description

Field	Description
remoteConfigs	The list of requested remote configs
remoteConfigForContextKey	Function for requesting specific remote config from the above list by the context key
remoteConfigForEmptyContextKey	Function for requesting the remote config from the above list with empy context key

`RemoteConfig` fields description

Field	Description
payload	JSON payload you have configured using the Qonversion dashboard.
experiment	Object (`Experiment`) with the experiment’s information.
source	Source (`RemoteConfigurationSource`) of the configuration.

`Experiment` description

Field	Description
identifier/id	Experiment’s identifier.
name	Experiment’s name. The same as you set in Qonversion. You can use it for analytical purposes.
group	Experiment’s group (`ExperimentGroup`) the user has been assigned to.

`ExperimentGroup` description

Field	Description
identifier/id	Experiment group’s identifier.
name	Experiment group’s name. The same as you set in Qonversion. You can use it for analytical purposes.
type	Type of the experiment’s group. Either control or treatment.

`RemoteConfigurationSource` description

Field	Description
identifier/id	Either experiment’s or remote config’s ID.
name	Either experiment’s or remote config’s name.
assignmentType	How the current payload was assigned: `automatic` (sticky, re-evaluated on targeting changes) or `manual` (overrides targeting, never re-evaluated until detach/archive/delete — including pins created by Freeze assignments).
type	One of the following: experiment control group, experiment treatment group, remote configuration.
contextKey	Context key assigned to either experiment or remote config.

Please, note:

If you’re using the Qonversion Experiments feature, the remoteConfigobject will also contain experiment-related fields.
Qonversion assigns eligible users to launched experiments once the remoteConfig is called. We also recommend paying attention to the Segmentation rules for the configuration. For how assignments, caching, and re-evaluation interact, see How targeting and assignment works.

Invalidate the config cache

Responses are cached in memory per context key, so a remoteConfig call may serve a cached copy without a network call. Call invalidateRemoteConfigsCache when the targeting inputs changed and you need the change reflected immediately — for example, after setting a batch of user properties your targeting depends on. The method performs no network request itself; it marks the cached values as stale, so the next remoteConfig / remoteConfigList call fetches a fresh evaluation from the server. You do not need to call it after identify — the SDK drops the config cache on identity changes automatically. Call it after SDK initialization: calling earlier throws on Android and is a no-op on iOS. For the full caching rules, see When a device fetches a config. Available since: iOS 6.14.0, Android 9.7.0, React Native 10.11.0, Flutter 11.10.0, Cordova 7.9.0, Capacitor 1.8.0, Unity 9.9.0.

Qonversion.shared().invalidateRemoteConfigsCache()

[[Qonversion sharedInstance] invalidateRemoteConfigsCache];

Qonversion.shared.invalidateRemoteConfigsCache()

Qonversion.getSharedInstance().invalidateRemoteConfigsCache();

Qonversion.getSharedInstance().invalidateRemoteConfigsCache();

Qonversion.getSharedInstance().invalidateRemoteConfigsCache();

Qonversion.GetSharedInstance().InvalidateRemoteConfigsCache();

Qonversion.getSharedInstance().invalidateRemoteConfigsCache();

Qonversion.getSharedInstance().invalidateRemoteConfigsCache();

4. Test changes before launch

Please, note, the guide below allows you to test only configurations created through the Remote Config dashboard section. To test configurations from the Experiments section, please, follow the test experimental changes before launch guide.

We highly recommend testing if your app works properly with the changes you want to roll out to your users. You can do so by following the following steps:

Copy the ID for your remote config

Copying the configuration ID from the Details panel

Pass the values to Qonversion SDK by using the attachUserToRemoteConfiguration method

This creates a manual assignment: it overrides targeting rules and is never re-evaluated — the pin survives config edits until you detach the user, or archive/delete the configuration (see Assignments: why evaluation is sticky). Attaching or detaching also drops the SDK’s in-memory config cache, so the next fetch reflects the change immediately.

Qonversion.shared().attachUser(toRemoteConfiguration: "your_remote_configuration_id") { success, error in
     // handle result
}

[[Qonversion sharedInstance] attachUserToRemoteConfiguration:@"your_remote_configuration_id" completion:^(BOOL success, NSError * _Nullable error) {
    // handle result
}];

Qonversion.shared.attachUserToRemoteConfiguration("your_remote_configuration_id", object : QonversionRemoteConfigurationAttachCallback {
    override fun onSuccess() {
        // handle success
    }

    override fun onError(error: QonversionError) {
        // handle error
    }
})

Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id", new QonversionRemoteConfigurationAttachCallback() {
    @Override
    public void onSuccess() {
        // handle success
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // handle error
    }
});

await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");

await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");

Qonversion.GetSharedInstance().AttachUserToRemoteConfiguration("your_remote_configuration_id", (success, error) =>
{
    // handle result
});

await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");

await Qonversion.getSharedInstance().attachUserToRemoteConfiguration("your_remote_configuration_id");

In case your user has already been attached to another configuration, use the detachUserFromRemoteConfiguration method.

Qonversion.shared().detachUser(fromRemoteConfiguration: "attached_remote_configuration_id") { success, error in
    // handle result
}

[[Qonversion sharedInstance] detachUserFromRemoteConfiguration:@"attached_remote_configuration_id" completion:^(BOOL success, NSError * _Nullable error) {
    // handle result
}];

Qonversion.shared.detachUserFromRemoteConfiguration("attached_remote_configuration_id", object : QonversionRemoteConfigurationAttachCallback {
    override fun onSuccess() {
        // handle success
    }

    override fun onError(error: QonversionError) {
        // handle error
    }
})

Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id", new QonversionRemoteConfigurationAttachCallback() {
    @Override
    public void onSuccess() {
        // handle success
    }

    @Override
    public void onError(@NonNull QonversionError error) {
        // handle error
    }
});

await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");

await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");

Qonversion.GetSharedInstance().DetachUserFromRemoteConfiguration("attached_remote_configuration_id", (success, error) =>
{
    // handle result
});

await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");

await Qonversion.getSharedInstance().detachUserFromRemoteConfiguration("attached_remote_configuration_id");

Call the Qonversion remoteConfig method. Now Qonversion SDK returns data associated with previously set remote config.
Validate your app logic without launching the configuration.

Pay attention before release

Do not forget to remove the usage of the attachUserToRemoteConfiguration method before your app release. Otherwise, all your users may be exposed to only one remote config.

5. Segment users

Qonversion Remote Config has flexible options to target a desired user segment. Segment users by:

App install date
- Use this option to assign the configuration only to new app installs.
App version
- Use this option to assign the configuration only for users with the app version with the new features implemented. This is your app’s version name, not its build number — versionName on Android (never versionCode) and CFBundleShortVersionString on iOS (never CFBundleVersion). See Matching on app version below.
Country
- Use this option to run new behavior only in selected countries.
Store
- Use this option to target only a specific store (Apple App Store or Google Play).
User’s active subscription
- Use this option to target only users with/without any active subscriptions or having a specific one.
Purchased product
- Use this option to target users based on their purchase history. You can select specific products or use (any) to match users who made at least one purchase, or (none) for users with no purchase history. Unlike “Active subscription”, this filter checks all purchases regardless of their current status (active, expired, or cancelled).
Last purchase date
- Use this option to target users based on when they made their most recent purchase. For example, you can target users whose last purchase was more than 60 days ago to identify churned users.

Adding a targeting rule to segment users

Targeting rules combine with a deterministic rollout percentage and sticky assignments: a user who receives the config keeps it, rule edits re-evaluate only automatic assignments (rolling out project by project), and manual pins are never re-evaluated. For the full evaluation model, see How targeting and assignment works.

Matching on app version

The SDK reports the version name your app displays to users — versionName on Android, CFBundleShortVersionString on iOS — and the App version rule compares your value against that. The Android versionCode and the iOS CFBundleVersion build numbers are never sent to Qonversion, so they cannot be targeted directly. If you need to segment by build number, set it as a user property and target it with a User properties rule instead. The ordering comparators (is greater than, is less than, is in range) compare both sides as semantic versions, so 1.10.0 is correctly greater than 1.9.0. Two cases are worth watching for, because neither reports an error — the rule simply targets the wrong set of users:

A build number used as the value. A bare number such as 24 passes the input validation, but it is then compared against version names like 1.8.4 — so is greater than matches nobody, and is less than matches everybody.
A version name that is not semver-shaped. If your app reports something like 2.0.9_08042026, it cannot be parsed as a version, and every ordering comparator matches nobody.

If your version name does not follow the MAJOR.MINOR.PATCH format, use is one of / is none of instead — they compare the string exactly and work with any format.

6. Launch the configuration

Once you have added all the necessary properties to your in-app configuration, validated changes in your app, and assigned desired segmentation rules, the only thing left is to click the Create button to move the configuration from Draft to Active state. Active configs are fetched lazily — nothing is downloaded until your code requests a config; see When a device fetches a config.

An active configuration in the Remote Configs list

7. Fallback files (optional)

To enhance the reliability of remote configurations, consider utilizing Qonversion fallback files. These files will serve as a backup in case of network provider errors or system failures, ensuring that your application continues to receive essential data and avoids any downtime. For more information on fallback files and how to install them, please refer to this page.

What’s Next

Overview

Get Started

Testing

Features

No-Code Builder

Remote Config

Experiments

Platform Resources

Stores Setup

SDK Migration Guides

AI-Ready

API Reference Guide

API Reference Guide v4

Create Remote Config

1. Select your app context to configure

2. Add attributes for your configuration

3. Integrate changes into your app

Configuration source

`RemoteConfigList` fields description

`RemoteConfig` fields description

`Experiment` description

`ExperimentGroup` description

`RemoteConfigurationSource` description

Invalidate the config cache

4. Test changes before launch

Pay attention before release

5. Segment users

Matching on app version

6. Launch the configuration

7. Fallback files (optional)

​1. Select your app context to configure

​2. Add attributes for your configuration

​3. Integrate changes into your app

​Configuration source

​RemoteConfigList fields description

​RemoteConfig fields description

​Experiment description

​ExperimentGroup description

​RemoteConfigurationSource description

​Invalidate the config cache

​4. Test changes before launch

​Pay attention before release

​5. Segment users

​Matching on app version

​6. Launch the configuration

​7. Fallback files (optional)

1. Select your app context to configure

2. Add attributes for your configuration

3. Integrate changes into your app

Configuration source

`RemoteConfigList` fields description

`RemoteConfig` fields description

`Experiment` description

`ExperimentGroup` description

`RemoteConfigurationSource` description

Invalidate the config cache

4. Test changes before launch

Pay attention before release

5. Segment users

Matching on app version

6. Launch the configuration

7. Fallback files (optional)