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 generatewrites 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 queryawait rudder.stores.buy({ offer: 'gold-bag' }); // a mutationconst balances = await rudder.session.wallet(); // { gems: 90, gold: 300 }Generate the client
Section titled “Generate the client”rudder loginrudder project use "My Game"rudder client generate --lang ts --output src/rudder.ts --game-address https://api.rudder.buildrudder login and rudder project use are needed once per machine and repository; see the
CLI. Any role of the project may generate a client.
| Flag | Meaning |
|---|---|
--lang | ts or csharp. Required. |
--output | The file to write. Required. |
--game-address | The address your game reaches Rudder at, https://api.rudder.build, written into the client as its default. |
--namespace | The C# namespace of the client, Game by default. |
--environment | staging or prod: the environment whose newest release the client follows. Without it, the environment of rudder.json. |
--project | Another 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.
What is generated
Section titled “What is generated”- A module with a function a client may call gets a class and a property named after the module
(
storesandStores). Functions markedserverare 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
rudderorsessionis 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.
Sign in a device
Section titled “Sign in a device”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);| Option | Meaning |
|---|---|
nickname | At most 32 characters. Set only while the player has none, so a rename by an operator stays. |
avatar | An http or https address. Set only while the player has none. |
language | A BCP 47 tag such as ru-RU. Replaces the stored one at every sign-in. |
region | An 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'.
Sign in with an account
Section titled “Sign in with an account”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.
The wallet
Section titled “The wallet”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.