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();Install
Section titled “Install”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/npm install @rudder/sdkThe 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:
rudder client generate --lang ts --output src/rudder.ts \ --game-address https://api.rudder.buildPass --release-version <version> to generate from an exact published version. Use the
version returned by rudder release publish when connecting a newly configured feature.
Browser games
Section titled “Browser games”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 generated client
Section titled “The generated client”- The class
Rudderhas a property per module (rudder.stores) andrudder.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
optionslast:signal, anAbortSignalthat cancels the call, and for a mutationidempotencyKey(see Errors and retries).
Options
Section titled “Options”The third argument of Rudder.signInDevice(key, deviceId, options):
| Option | Meaning |
|---|---|
address | The address of Rudder. Without it the client uses the address given to --game-address, or the origin of the page. |
attempts | How many times a request is sent before its failure is thrown, 5 by default. |
fetch | The function that sends the requests, fetch by default. |
nickname, avatar, language, region | The profile of the player (see Sign in a device). |
const rudder = await Rudder.signInDevice(sdkKey, deviceId, { nickname: playerName, language: navigator.language,});Errors
Section titled “Errors”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).
Without a generated client
Section titled “Without a generated client”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' });