rudder-csharp-sdk/skills/rudder-csharp-sdk/SKILL.md

---
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.