106 lines
4.9 KiB
Markdown
106 lines
4.9 KiB
Markdown
|
---
|
||
|
|
name: rudder-csharp-sdk
|
||
|
|
description: Use when working with the Rudder C# SDK Rudder.Core (namespace RudderSdk.Core) — client init, transports, auth/session lifecycle, and the per-domain services (player, stores, inventory, battle pass, quests, leaderboards, remote config, scenarios, storage, realtime).
|
||
|
|
---
|
||
|
|
|
||
|
|
# Rudder C# SDK (Rudder.Core)
|
||
|
|
|
||
|
|
.NET client SDK for the Rudder LiveOps platform. NuGet package `Rudder.Core`,
|
||
|
|
namespace `RudderSdk.Core` (DTOs under `RudderSdk.Core.Models.*`). Targets
|
||
|
|
`netstandard2.1` (works in Unity, .NET, Xamarin). JSON: Newtonsoft.Json
|
||
|
|
(`JToken`/`JObject` appear in public models). Everything is `async` with an
|
||
|
|
optional `CancellationToken` as the last parameter.
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
```
|
||
|
|
dotnet add package Rudder.Core
|
||
|
|
```
|
||
|
|
|
||
|
|
## Client init
|
||
|
|
|
||
|
|
Only `BaseUrl` and `ProjectKey` are required; the constructor throws
|
||
|
|
`ArgumentException` when either is missing. Production API:
|
||
|
|
`https://api.rudder.build`. The project key is issued in the dashboard
|
||
|
|
(https://app.rudder.build/).
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
using RudderSdk.Core;
|
||
|
|
|
||
|
|
var client = new RudderClient(new RudderClientOptions
|
||
|
|
{
|
||
|
|
BaseUrl = "https://api.rudder.build",
|
||
|
|
ProjectKey = "your-project-key"
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
Defaults injected when the option is null (see reference/client.md for the
|
||
|
|
full options surface and the abstraction interfaces):
|
||
|
|
|
||
|
|
- `Transport` → `HttpClientTransport` (10 s request timeout)
|
||
|
|
- `TokenStore` → `InMemoryTokenStore` (session lost on restart — plug a
|
||
|
|
durable `ITokenStore` for production)
|
||
|
|
- `DeviceIdProvider` → `GuidDeviceIdProvider` (new GUID per run — plug a
|
||
|
|
persistent `IDeviceIdProvider` for production)
|
||
|
|
|
||
|
|
`RealtimeUrl` + `RealtimeTransportFactory` are required only for
|
||
|
|
`client.Realtime`; there is no default websocket transport in Rudder.Core.
|
||
|
|
|
||
|
|
## Request pipeline (applies to every service)
|
||
|
|
|
||
|
|
- All calls go to `{BaseUrl}/sdk/v1/...` with the stored access token as a
|
||
|
|
`Bearer` header.
|
||
|
|
- A 401 triggers one single-flight token refresh
|
||
|
|
(`POST /sdk/v1/authorization/refresh`) and one transparent retry. If the
|
||
|
|
refresh fails, tokens are cleared and `Auth.AuthStateChanged` fires
|
||
|
|
`RudderAuthState.SignedOut` — the game must sign in again.
|
||
|
|
- Non-success statuses throw `RudderApiException` subclasses; network
|
||
|
|
failures throw `RudderNetworkException` (`StatusCode == 0`). See
|
||
|
|
reference/errors.md.
|
||
|
|
- `client.Update(deltaTime)` must be called every frame — it pumps the
|
||
|
|
scenario runtime (wait-node deadlines) and the realtime transport.
|
||
|
|
|
||
|
|
## Capability map
|
||
|
|
|
||
|
|
| Domain | Entry point | Reference |
|
||
|
|
|---|---|---|
|
||
|
|
| Client, options, transports, abstractions | `RudderClient`, `RudderClientOptions` | reference/client.md |
|
||
|
|
| Errors, exceptions, error codes | `RudderApiException`, `RudderErrorCodes` | reference/errors.md |
|
||
|
|
| Auth (device/custom login, refresh, logout) | `client.Auth` | reference/auth.md |
|
||
|
|
| Player profile + wallets | `client.Player` | reference/player.md |
|
||
|
|
| Remote config (cached typed reads) | `client.RemoteConfig` | reference/remote-config.md |
|
||
|
|
| Player key-value storage | `client.Storage` | reference/storage.md |
|
||
|
|
| Project (global) storage | `client.ProjectStorage` | reference/project-storage.md |
|
||
|
|
| Stores and offer purchases | `client.Stores` | reference/stores.md |
|
||
|
|
| Leaderboards | `client.Leaderboards.FindBySlug(slug)` | reference/leaderboards.md |
|
||
|
|
| Inventory | `client.Inventory` | reference/inventory.md |
|
||
|
|
| Battle pass | `client.BattlePass` (+ scenario session) | reference/battlepass.md |
|
||
|
|
| Quests (global) | `client.Quests` | reference/quests.md |
|
||
|
|
| Scenarios (event-driven plans, node sessions) | `client.Scenario` | reference/scenarios.md |
|
||
|
|
| Realtime websocket | `client.Realtime` | reference/realtime.md |
|
||
|
|
|
||
|
|
Important cross-cutting facts:
|
||
|
|
|
||
|
|
- Battle pass state is tied to a scenario battle-pass node: every
|
||
|
|
`BattlePassService` call carries `ScenarioId`/`NodeId` (mutations also
|
||
|
|
`RunId`). During a scenario run, `BattlePassSession` supplies them — prefer
|
||
|
|
the session API inside a run.
|
||
|
|
- Global quests (`client.Quests`) are distinct from scenario quest nodes
|
||
|
|
(`Scenario.OnQuest` → `QuestSession`).
|
||
|
|
- Mutations that take an idempotency key auto-generate a random GUID when the
|
||
|
|
key is omitted (`Stores.PurchaseAsync`, `ProjectStorage.SaveAsync`,
|
||
|
|
`BattlePass.PurchasePremiumAsync`). Pass a stable key to make retries safe.
|
||
|
|
- Generated DTOs (`// Code generated by apigen`) use nullable properties and
|
||
|
|
`JsonProperty` snake_case names; never edit them by hand.
|
||
|
|
|
||
|
|
## Relationship to the Unity package (rudder.sdk)
|
||
|
|
|
||
|
|
`rudder.sdk` (UPM, liveops-unity-sdk) wraps `Rudder.Core.dll` with Unity
|
||
|
|
adapters: `UnityWebRequest` transport, `PlayerPrefs` token store, a websocket
|
||
|
|
realtime transport, and a `Rudder` bootstrap component
|
||
|
|
(`RudderSdk.Unity` namespace). The domain services and models are the same
|
||
|
|
ones documented here — for Unity games, consume them through the package's
|
||
|
|
adapters instead of wiring `RudderClientOptions` by hand. Unity requires
|
||
|
|
`com.unity.nuget.newtonsoft-json` since Rudder.Core serializes with
|
||
|
|
Newtonsoft.Json.
|