Experiments
This API is used to read experiment assignments in the browser, and to list experiments and assign users in bulk on servers.
For more information about Experiments, visit the Experiments Guide.
const gamebeastExperiments = gamebeast.experiments;Enrollment happens automatically: evaluating a configuration enrolls the user in its eligible experiments, and the values returned by Configs 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.
Client methods
Types
interface ExperimentAssignment {
experimentId: number;
experimentName: string | null; // null until the experiment catalog has loaded.
groupId: number;
groupLabel: string | null; // null until the experiment catalog has loaded.
configuration: string; // The ID of the configuration the experiment applies to.
source: "weightedHash" | "roundRobin" | "manual";
}assignments
readonly ExperimentAssignment[]return type
The current user's active assignments across every fetched configuration, ordered by experiment id. Empty until the first configuration has loaded, and cleared when the user changes with identify or resetIdentity.
Usage
for (const assignment of gamebeastExperiments.assignments) {
console.log(`In group ${assignment.groupLabel} of ${assignment.experimentName}`);
}onAssignmentsChanged(callback)
Unsubscribereturn type
Calls callback with the full list whenever it changes, including when experiment names finish loading.
callback(assignments: readonly ExperimentAssignment[]) => voidCalled with the updated assignment list.
Usage
gamebeastExperiments.onAssignmentsChanged((assignments) => {
analytics.setUserProperties({
experiments: assignments.map((a) => `${a.experimentName}:${a.groupLabel}`),
});
});Server methods
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, ... }]