Installation

If you haven't created a project in the Gamebeast dashboard yet, please start with the Getting Started guide. When you create the project, pick Other as its platform (or Unity / Discord if this is the server side of one of those games). Gamebeast validates markers against the project's platform, and Roblox projects expect the Roblox SDK's marker format, so give your app its own project rather than reusing a Roblox one.

This SDK runs on Node.js 20+, Bun, Deno, edge runtimes and serverless functions. For code that runs in the browser, see the JavaScript SDK.

Installing the SDKCopy Anchor Link

The SDK is published to npm as @gamebeast/node. It ships ESM and CommonJS builds with TypeScript types, and uses the runtime's built-in fetch. The source is on GitHub.

npm install @gamebeast/node

Creating an API keyCopy Anchor Link

The Node.js SDK uses a Server Key: a private key that can evaluate configurations and assign experiments for any user.

1. In the dashboard, open Project Settings from the left side.
2. Press Create API Key and create a Server Key.
3. Copy the key before closing the popup. You won't be able to see it again.
4. Store it as a secret, for example in an environment variable such as GAMEBEAST_SERVER_KEY.

Start the SDKCopy Anchor Link

import { GamebeastServer } from "@gamebeast/node";

// One instance per process, shared by every request.
export const gamebeast = new GamebeastServer({
  apiKey: process.env.GAMEBEAST_SERVER_KEY!,
});

gamebeast.markers.send("server_started");

// Deliver buffered markers before the process exits.
process.on("SIGTERM", async () => {
  await gamebeast.shutdown();
  process.exit(0);
});

And that's it! You're now ready to start sending data to the Gamebeast dashboard.

Serverless functionsCopy Anchor Link

In short-lived processes, turn off background polling and flush markers before the handler returns:

const gamebeast = new GamebeastServer({
  apiKey: process.env.GAMEBEAST_SERVER_KEY!,
  autoRefresh: false, // call gamebeast.configs.refresh() when you need current base values
});

export async function handler(event) {
  gamebeast.markers.send(
    "checkout_completed",
    { total: event.total },
    { distinctId: event.userId }
  );
  await gamebeast.flush();
  return { statusCode: 200 };
}

Testing against developmentCopy Anchor Link

The SDK targets the Production environment unless you pass environment. While you're building, point it at Development so test data stays out of your live numbers:

new GamebeastServer({ apiKey: process.env.GAMEBEAST_SERVER_KEY!, environment: "development" });

Custom environments work too: pass the name from Copy environment name in the dashboard's environment selector, such as "staging". Configurations and experiments use custom environments directly. Markers and cohort checks only support Production and Development, so they go to Development from a custom environment, and the SDK warns you about it once at startup.

Using it with a web front endCopy Anchor Link

If your app also runs code in the browser, use the JavaScript SDK there, with an SDK Key.

• Create the GamebeastServer in a server-only module (route handlers, server actions, API routes).
• Use the same user id for distinctId: user.id here and identify(user.id) in the browser. The two then report as one user, and a configuration evaluated here matches what that user sees in the browser.
• Keep @gamebeast/node and @gamebeast/js on the same version. They're always released together.

Versions and updatesCopy Anchor Link

The SDK follows semantic versioning: a new major version is the only kind that can break your code. It installs a shared internal package, @gamebeast/core, automatically; don't depend on it directly.

SDK_VERSION is the installed version, which is useful in bug reports:

import { SDK_VERSION } from "@gamebeast/node";

Release notes are on the GitHub releases page.