Configs

For more information about Configurations, visit the Configurations Guide.

const gamebeastConfigs = gamebeast.configs;

PathsCopy Anchor Link

Values are addressed by path. The first segment is the configuration's ID, which you copy from its ⋯ menu in the dashboard with Copy ID:

• "game-settings.PlayerSpeed" reads the PlayerSpeed key of the game-settings configuration.
• "game-settings.UI.ButtonColor" reaches deeper, and "game-settings.Levels.0" indexes an array.
• "game-settings" on its own returns the whole configuration document.
• ["game-settings", "key.with.dots"] is the array form, for keys that contain a ..

Values are always deep copies, so changing a returned object never affects what the SDK holds.

FallbacksCopy Anchor Link

Every read accepts an optional fallback. With one, you get the fallback when the value is missing, null, not loaded yet, or a different JSON type than the fallback (a mismatch is logged once). That makes the fallback both a default and a type check:

const speed = gamebeastConfigs.get("game-settings.PlayerSpeed", 16); // number, always

Without a fallback, get returns undefined when there's no value. The type parameter (get<number>(…)) is not checked at runtime, so prefer a fallback where the type matters.

Configurations are evaluated for the current user: if they're enrolled in an active experiment, the values already include their group's changes.

Configurations load on demand: the first read of a configuration fetches it. Listing it in the configurations option fetches it at startup instead and makes isReady / onReady wait for it. Values are cached in localStorage per user and app version, so on the next visit they're available immediately and then refreshed in the background.

While the page is visible, the SDK re-checks configurations every configRefreshIntervalSeconds (60 by default), and again when the tab becomes visible. An unchanged configuration costs one small round trip.

get(path, fallback?)Copy Anchor Link

→T | undefinedreturn type

Reads a value. Returns the fallback (or undefined without one) when the configuration hasn't loaded yet. Prefer observe when the value may still be loading.

UsageCopy Anchor Link

const speed = gamebeastConfigs.get("game-settings.PlayerSpeed", 16);
const color = gamebeastConfigs.get("game-settings.UI.ButtonColor", "blue");

// Whole document, typed by you
interface GameSettings {
  PlayerSpeed: number;
}
const settings = gamebeastConfigs.get<GameSettings>("game-settings");

observe(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback with the current value as soon as it's available, and again each time it changes. This is the best fit for values that may still be loading, and for UI that should follow live changes.

UsageCopy Anchor Link

const stop = gamebeastConfigs.observe("game-settings.PlayerSpeed", (speed) => {
  player.speed = typeof speed === "number" ? speed : 16;
});

onChanged(path, callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback whenever the value at path changes. It does not fire for the initial load; use observe for that.

UsageCopy Anchor Link

gamebeastConfigs.onChanged("game-settings.MaintenanceMode", (on) => {
  if (on === true) showMaintenanceBanner();
});

isReadyCopy Anchor Link

→booleanreturn type

True once every configuration listed in the configurations option has loaded (from the cache or the network) or failed permanently, for example because it doesn't exist. Configurations fetched on demand don't affect it.

onReady(callback)Copy Anchor Link

→Unsubscribereturn type

Calls callback once isReady becomes true, or immediately if it already is.

UsageCopy Anchor Link

gamebeastConfigs.onReady(() => startGame());

ready(options?)Copy Anchor Link

→Promise<boolean>return type

Resolves true once ready, or false if timeoutMs passes first. It never rejects, so you can always await it before rendering without a try.

UsageCopy Anchor Link

if (!(await gamebeastConfigs.ready({ timeoutMs: 3_000 }))) {
  console.warn("Using default settings: configurations did not load in time.");
}

refresh()Copy Anchor Link

→Promise<void>return type

Re-fetches every known configuration now, in addition to the background refresh. Resolves once the requests have settled.