Skip to main content

Enhanced (JSON) Remote Configs

Configuration Guide​

Enhanced Remote Configs introduce configurations with JSON values. Use this guide to structure and consume JSON values effectively.

JSON Editor and Type Selector​

The dashboard provides a JSON editor for creating and editing configs with nested JSON structures. When you choose the JSON type in the editor:

  • Validation is optional; if your SDK cannot parse JSON natively, you can treat the value as a raw string.
  • A full‑screen mode makes it easier to edit large JSON bodies.
  • Type selector options (String, JSON) are available when creating an Enhanced config.

Creating JSON values​

  • When creating an enhanced Remote Config, choose JSON as the value type.

  • Use the built‑in JSON editor to input your configuration. Nested objects and arrays are supported. Example:

    {
      "difficultySettings": {
        "easy": 1.0,
        "hard": 1.5
      },
      "availableModes": ["campaign", "arena", "survival"],
      "eventMessage": "Welcome to the Arena!"
    }

  • Keep JSON keys consistent; avoid dynamic keys that require client updates.

Validating JSON​

The editor supports basic syntax highlighting. However, some SDKs may not include built‑in JSON parsers. If you rely on JSON parsing:

  • In Unity/C#, use JsonUtility or Newtonsoft.Json.
  • In iOS/Objective‑C or Swift, use JSONSerialization.
  • In Android/Java, use org.json or a third‑party library.

Consider implementing fallback logic in case parsing fails.

Consuming JSON in SDKs​

After fetching a JSON Remote Config via GetRemoteConfigsValueAsString(key), parse the string into your game model. Always include a default JSON string to ensure safe operation if the config is missing or invalid.

Identification & Versioning​

Enhanced Remote Configs generate a unique identifier (id) and a version number (vsn) each time a configuration is created or updated.

When identifiers are created​

  • Upon saving a new enhanced Remote Config, the system assigns an identifier (e.g., Ag6VBxcGzjqG50XImbVGUg==).
  • Each time you edit the config, the version number increments (starting from 0). The identifier remains the same.

Where identifiers appear​

  • In the Remote Config version history popup, the column displays the current version.
  • In event data (for SDKs supporting Enhanced Remote Configs), the configurations_v3 array contains objects like { "id": "Ag6VBxcGzjqG50XImbVGUg==", "key": "new_remote_cfg1", "vsn": 1 }.
  • This allows you to correlate events with the exact configuration version that was active when the event occurred.

How to use versioning​

  • Debugging: When monitoring metrics, filter by specific versions to see the impact of configuration changes.
  • Rollbacks: If a new version causes issues, you can revert the value in the dashboard; the version number increases but you know which version had a problem.
  • A/B tests: Version numbers help differentiate base configs from variant overrides (override versions may use vsn = 0 with id = null).

Event Annotation​

GA SDKs attach Remote Config information to each event so you can analyse behaviour by configuration. Instead of sending the full config payload in every event, Enhanced Remote Configs introduces lightweight annotations:

  • The SDK annotates events with a map of config keys to {id, vsn} pairs (e.g., "reward_mult": {"id": "Pe7le...", "vsn": 3}).
  • This approach reduces bandwidth and processing overhead while retaining the ability to attribute events to the correct configuration.
  • Older SDKs continue to support full‑payload annotations for backward compatibility.

Handling A/B overrides​

When an A/B Test variant overrides a Remote Config value, the init response includes ab_id and ab_variant_id. The overridden config entry may have id = null and vsn = 0. Events annotate this override similarly, so you can attribute behaviour to the A/B variant. After the variant period ends, the normal config resumes.

Compatibility and Migration Notes​

  • Legacy SDKs (Backward-compatible configs) will continue to receive only backward-compatible string configs. They ignore enhanced JSON configs. Events they send include full key–value annotations in the configurations property.
  • New SDKs (Enhanced configs enabled) will receive both backward-compatible and enhanced configs. They annotate events using configurations_v3 with identifier and version fields.
  • Backward-compatible editing: You cannot convert a backward-compatible config to the enhanced format. When copying an backward-compatible config, choose the desired format explicitly.

SDKs Compatible with Enhanced Remote Configs​

  • C++ SDK version 5.0.0 or higher
  • Android SDK version 7.0.0 or higher
  • iOS SDK version 5.0.0 or higher
  • Unity SDK version 8.0.0 or higher
  • Unreal SDK version 6.0.0 or higher

Best practices​

  • Document your JSON schema in the config description.
  • Use version numbers implicitly provided by the system to manage changes.
  • Avoid extremely large JSON objects; keep payloads efficient to minimise bandwidth.