Experiments
This API is used to list active experiments and assign users in bulk on your server.
For more information about Experiments, visit the Experiments Guide.
const gamebeastExperiments = gamebeast.experiments;Enrollment happens automatically: evaluating a configuration with configs.evaluate enrolls the user in its eligible experiments, and the values it returns already include the assigned group's changes. You don't need this service to run an experiment. It's for display, analytics segmentation, debugging, and assigning users ahead of time.
list(unitType?)
readonly SdkExperimentDescriptor[]return type
The active experiments for a unit type, from the configuration snapshot. Empty until configurations have loaded.
unitType"user" | "server"Which experiments to list. Defaults to "user".
Types
interface SdkExperimentDescriptor {
id: number;
name: string;
unitType: "user" | "server";
assignmentMode: "weightedHash" | "roundRobin";
baseConfigurationId: number;
autoAssignment: boolean;
permanentEnrollment: boolean;
requiredProperties: string[];
startsAt: string;
endsAt: string | null;
groups: Array<{ id: number; label: string; weight: number | null; ordinal: number }>;
}Usage
const running = gamebeastExperiments.list().map((experiment) => experiment.name);assign(units, options?)
Promise<Map<string, AssignmentEntry[]>>return type
Resolves experiment assignments for many users at once. The backend enrolls them exactly as evaluation would, and records exposure. Use it to assign users before they next play, or to look up the groups of a batch of users.
The SDK splits large requests into batches of 250 users. The result has an entry for every valid id. If any batch fails, the call rejects with a GamebeastError, because a partial answer would read as "not enrolled" for the missing users.
unitsArray<string | { distinctId: string; properties?: Properties }>The users to assign: ids, or ids with their own targeting properties. A repeated id uses its last entry.
options.sharedPropertiesPropertiesProperties for every user. A user's own properties win on a name clash. Optional.
options.unitType"user" | "server"Defaults to "user".
Types
interface AssignmentEntry {
experimentId: number;
groupId: number;
automaticGroupId: number | null;
overrideGroupId: number | null;
status: "active" | "unenrolled";
source: "weightedHash" | "roundRobin" | "manual";
assignmentVersion: number;
}Usage
const assignments = await gamebeastExperiments.assign(
["u1", "u2", { distinctId: "u3", properties: { plan: "pro" } }],
{ sharedProperties: { region: "eu" } }
);
assignments.get("u1"); // [{ experimentId, groupId, status, source, ... }]