edmand46
1029f08fba
- scenarios.md rewritten for server-side execution + effects API - realtime.md deleted; realtime/planstore references purged from docs - CHANGELOG Unreleased: major bump + migration table
106 lines
4.8 KiB
Markdown
106 lines
4.8 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, scenario trigger, scenario effects, storage).
|
|
---
|
|
|
|
# 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)
|
|
|
|
`Clock` defaults to `DateTimeOffset.UtcNow`; override in tests. There is no
|
|
realtime websocket client 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
|
|
effects client (30s pending heartbeat and wait-node deadline checks).
|
|
|
|
## 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 effect) | reference/battlepass.md |
|
|
| Quests (global) | `client.Quests` | reference/quests.md |
|
|
| Scenario trigger | `client.Scenario` | reference/scenarios.md |
|
|
| Scenario effects | `client.Effects.On*` | reference/scenarios.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, `BattlePassEffect` supplies them — prefer
|
|
the effect API inside a run.
|
|
- Global quests (`client.Quests`) are distinct from scenario quest nodes
|
|
(`Effects.OnQuest` → `QuestEffect`).
|
|
- 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, 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.
|