Skip to content

TypeScript client SDK for web games

import { Rudder } from './rudder';
const rudder = await Rudder.signInDevice(sdkKey, deviceId);
const stores = await rudder.stores.stores();
await rudder.stores.buy({ offer: 'gold-bag' });
const balances = await rudder.session.wallet();

The SDK is the package @rudder/sdk of the Rudder package registry, which needs no account. Point the scope @rudder at it in the .npmrc of your project, then install:

@rudder:registry=https://hub.rudder.build/api/packages/rudder/npm/
Terminal window
npm install @rudder/sdk

The package @rudder/sdk is ESM and has no runtime dependencies. It runs in the browser and in Node.

Then, in a repository where rudder project use chose the project, generate the client:

Terminal window
rudder client generate --lang ts --output src/rudder.ts \
--game-address https://api.rudder.build

Pass --release-version <version> to generate from an exact published version. Use the version returned by rudder release publish when connecting a newly configured feature.

A browser answers a call from a page only when Rudder allows the origin of the page. Each environment has its list: on Settings of the project, Allowed origins under the environment, one origin per line, then Save origins. Only the owner changes it.

  • An origin is a scheme, a host and an optional port: https://play.example.com, http://localhost:5173. No path.
  • At most 20 origins per environment. * allows any origin.
  • Add the origins of each build: your local dev server to Staging, the sites that host the game to Production.

You can read the staging key and origins with rudder environment show --env staging --json and save the full origins list with rudder environment set-origins --env staging --file origins.json. The JSON file contains {"allowedOrigins":["http://localhost:5173"]}. Retain existing origins your game needs before saving.

The same holds for a Unity WebGL build: the browser calls Rudder from the page that hosts the game, so add the origin of that page. Native builds and Node need no origin.

  • The class Rudder has a property per module (rudder.stores) and rudder.session, the session of the SDK.
  • The types of a module live in a namespace of the same name as its class (Stores.BuyArguments, Stores.OfferState), so two modules may declare types of the same name.
  • An optional property is ?, a nullable one | null, an enum a union of strings, a time an ISO 8601 string.
  • Every method takes options last: signal, an AbortSignal that cancels the call, and for a mutation idempotencyKey (see Errors and retries).

The third argument of Rudder.signInDevice(key, deviceId, options):

OptionMeaning
addressThe address of Rudder. Without it the client uses the address given to --game-address, or the origin of the page.
attemptsHow many times a request is sent before its failure is thrown, 5 by default.
fetchThe function that sends the requests, fetch by default.
nickname, avatar, language, regionThe profile of the player (see Sign in a device).
const rudder = await Rudder.signInDevice(sdkKey, deviceId, {
nickname: playerName,
language: navigator.language,
});

A refused call throws RudderError from @rudder/sdk with code, message and the HTTP status:

import { RudderError } from '@rudder/sdk';
try {
await rudder.stores.buy({ offer: offerKey });
} catch (error) {
if (error instanceof RudderError && error.code === 'insufficient') {
showNotEnoughGems();
} else {
throw error;
}
}

The codes are those the module declares (Stores: not_on_sale, limit_reached, sold_out, …) and those of Rudder (Error codes).

rudder.session (a Session of @rudder/sdk) calls any function by name, for a module the client was generated without:

const top = await rudder.session.query<{ places: unknown[]; players: number }>(
'leaderboards', 'top', { board: 'arena', count: 10 });
await rudder.session.mutation('quests', 'claim', { quest: 'daily-play' });