Skip to content

Client SDKs for games

A game client talks to Rudder through two parts:

  • The SDK core for your engine: Unity and .NET or TypeScript. It signs the device in, sends the calls, retries them safely and turns refusals into typed errors. It has no dependencies.
  • The client of your project, one file that rudder client generate writes from a release: a class per module, a method per function a client may call, and the types of their arguments and results.
const rudder = await Rudder.signInDevice(sdkKey, deviceId);
const stores = await rudder.stores.stores(); // a query
await rudder.stores.buy({ offer: 'gold-bag' }); // a mutation
const balances = await rudder.session.wallet(); // { gems: 90, gold: 300 }
Terminal window
rudder login
rudder project use "My Game"
rudder client generate --lang ts --output src/rudder.ts --game-address https://api.rudder.build

rudder login and rudder project use are needed once per machine and repository; see the CLI. Any role of the project may generate a client.

FlagMeaning
--langts or csharp. Required.
--outputThe file to write. Required.
--game-addressThe address your game reaches Rudder at, https://api.rudder.build, written into the client as its default.
--namespaceThe C# namespace of the client, Game by default.
--environmentstaging or prod: the environment whose newest release the client follows. Without it, the environment of rudder.json.
--projectAnother project than the one of rudder.json.

The client follows a release, not the draft: it matches what the game reaches. Generate it again when a release adds or changes a function or a type, and commit the file with your game. An environment without a release yet is refused: publish one first.

  • A module with a function a client may call gets a class and a property named after the module (stores and Stores). Functions marked server are left out: a client cannot call them.
  • Each such function is a method. A query reads, a mutation changes data and carries an idempotency key (see Errors and retries).
  • Every type the module declares is generated, so the results are typed to the field. A module named rudder or session is refused: the client uses these names.

To generate from a specific published version, pass --release-version <version> to rudder client generate. After publishing staging, use the returned version. The generated file identifies its environment and release.

signInDevice (SignInDevice in C#) takes the SDK key of an environment and a device id. The first sign-in of a device id creates a player; every later one signs the same player in. Choose an id that stays the same on the device, and keep it yourself: the session lives in memory only, so each launch of the game signs in again.

import { Session } from '@rudder/sdk';
const session = await Session.signInDevice(key, deviceId);
using RudderSdk;
var session = await Session.SignInDevice(key, deviceId);
OptionMeaning
nicknameAt most 32 characters. Set only while the player has none, so a rename by an operator stays.
avatarAn http or https address. Set only while the player has none.
languageA BCP 47 tag such as ru-RU. Replaces the stored one at every sign-in.
regionAn ISO 3166-1 alpha-2 code such as RU. Replaces the stored one at every sign-in.

The access token lives 24 hours. When a call is refused as unauthorized, the SDK signs the device in again once and sends the call again, so a long session needs nothing from you.

A banned player is refused at sign-in and on every call with player_banned, until the ban ends. A player an operator deleted is refused with player_deleted.

The player id is rudder.session.playerId (rudder.Session.PlayerId in C#). Hand it to your game server when it needs to call for this player: the server SDK does that with the server key.

The session names the environment of the SDK key: rudder.session.environment (rudder.Session.Environment in C#), 'staging' or 'prod'.

signIn (SignInAsync in C#) signs a player in with the account a provider of the environment gave the game, and linkProvider (LinkProviderAsync in C#) attaches such an account to the player of a session. The platform verifies the account itself; the payload of each provider and what the platform checks are in Authentication.

import { Session } from '@rudder/sdk';
const session = await Session.signIn(key, {
provider: 'google',
payload: { idToken },
});
await session.linkProvider({ provider: 'vk', payload: { code, deviceId } });
using RudderSdk;
var session = await Session.SignInAsync(key, new ProviderSignIn
{
Provider = "google",
Payload = new Dictionary<string, object?> { ["idToken"] = idToken },
});
await session.LinkProviderAsync(new ProviderSignIn
{
Provider = "vk",
Payload = new Dictionary<string, object?> { ["code"] = code, ["deviceId"] = deviceId },
});

A session made with a provider, unlike a device session, cannot be renewed by the SDK: when its token expires the game signs in again. unlinkIdentity(provider, subject) (UnlinkIdentity in C#) detaches one identity; the last one of a player cannot be detached.

session.wallet() (Session.Wallet() in C#) returns the balance of every currency of the release that the client may see. A currency an operator hides from clients is left out, and modules still use it.