Remote Config

Remote Config

Remote config is one JSON object per Game Project. Use it for values that you must change without a new game release. Examples are kill switches, balance values, announcements, and the minimum client version. A client can read it before the player signs in. It needs only a publishable or secret API key that is pinned to the Game Project.

Edit the config

In the control panel, open Game Projects, select a Game Project, then open Game Project settings. The Remote config editor accepts a top-level JSON object of 64 KiB maximum. A new Game Project starts with an empty object. No environment variables or other setup are necessary. The editor keeps old revisions, and you can roll back to one.

{
  "minimum_client_version": "1.4.0",
  "maintenance_mode": false,
  "daily_reward_multiplier": 1.5
}

GG Scale does not read the values. Your game client depends on the key names and value types, so keep them stable.

Fetch and revalidate

Call GET /v1/config before the sign-in flow. A 200 response body is the config object. The response also has an ETag header and Cache-Control: no-cache.

curl -s http://localhost:8080/v1/config \
  -H "Authorization: Bearer <api_key>"

Keep the ETag. Send it as If-None-Match on the next request:

curl -s http://localhost:8080/v1/config \
  -H "Authorization: Bearer <api_key>" \
  -H 'If-None-Match: "remote-config-…"'

If the config did not change, the server returns 304 Not Modified with no body. On 200, replace the cached object and the ETag together.

Use a short timeout. If a request fails, keep the last valid config. On the first run, use an empty object as the fallback.

Minimum client version

Fetch the config before you show the sign-in screen. Then compare the build version with minimum_client_version. Use the same version scheme as your release pipeline. Do not compare the versions as plain strings. For example, 1.10.0 is newer than 1.9.0, but a string comparison puts it first.

A possible flow:

1. Fetch or revalidate the remote config.
2. If maintenance_mode is true, show a maintenance screen. Do not continue to sign-in.
3. Parse minimum_client_version and the client version as semantic versions.
4. If the client is older, show an update screen with the store link.
5. If not, continue to anonymous sign-in, sign-up, or login.

A version value can be missing or malformed. Give the client a fallback for this case. For most games, ignore that one key and continue. This is safer than a lock-out of all players because of a typing error in the editor.

Common errors

Status	Meaning
400 api key has no project pin	The key is valid for the full Account Tenant, not for one Game Project. Use a key that is pinned to the Game Project.
401	The API key is missing or not valid.

Full reference: the /v1/config operation.