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 web 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 a web app its own project rather than reusing a Roblox one.

This SDK runs in browsers, web apps and web workers. For your backend, see the Node.js SDK.

Installing the SDKCopy Anchor Link

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

npm install @gamebeast/js

Creating an API keyCopy Anchor Link

The JavaScript SDK uses an SDK Key: a public key scoped to one project, safe to ship in browser code.

1. In the dashboard, open Project Settings from the left side.
2. Press Create API Key and create an SDK Key.
3. Copy the key before closing the popup. You won't be able to see it again.

Start the SDKCopy Anchor Link

import { GamebeastClient } from "@gamebeast/js";

// One instance per page; a module-level singleton works well.
export const gamebeast = new GamebeastClient({
  apiKey: "YOUR_SDK_KEY", // Replace with your SDK Key.
});

gamebeast.markers.send("page_opened", { path: location.pathname });

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

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 GamebeastClient({ apiKey: "YOUR_SDK_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 backendCopy Anchor Link

Apps with a server of their own (Next.js, Remix, Nuxt, an Express API behind a single-page app) often use both SDKs: this one in code that runs in the browser, and the Node.js SDK in route handlers, server actions and API routes.

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

A GamebeastClient created while a page renders on the server stays inert; see Server-side rendering.

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/js";

Release notes are on the GitHub releases page.