rudder-csharp-sdk/README.md

Rudder.Core

.NET client SDK for the Rudder LiveOps platform: authentication, player profile, stores, battle pass, quests, leaderboards, inventory, remote config, scenarios (server-driven effects), and storage.

• Target framework: netstandard2.1 (works in Unity, .NET, Xamarin).
• JSON: Newtonsoft.Json.
• Naming follows the cross-SDK glossary: .spec/sdk-glossary.md in the monorepo root.

Install

dotnet add package Rudder.Core

Quickstart

using RudderSdk.Core;

var client = new RudderClient(new RudderClientOptions
{
    BaseUrl = "https://api.example.com",
    ProjectKey = "your-project-key"
});

// Sign in with the device id.
await client.Auth.LoginWithDeviceAsync(region: "en", language: "en");

// First call: read the player profile.
var profile = await client.Player.GetProfileAsync();
Console.WriteLine(profile.Player.Id);

// Buy an offer (idempotency key is generated when omitted).
var purchase = await client.Stores.PurchaseAsync("main-store", "offer-1");

// Pump the effects client (30s pending heartbeat + wait deadlines) every frame.
client.Update(deltaTime);

Only BaseUrl and ProjectKey are required. Transport, TokenStore and DeviceIdProvider default to HttpClientTransport, InMemoryTokenStore and GuidDeviceIdProvider; inject your own implementations via RudderClientOptions for persistence or a custom HTTP stack.

Services

Property	Service	Main operations
Auth	AuthService	LoginWithDeviceAsync, RefreshAsync, Logout, AuthStateChanged
Player	PlayerService	GetProfileAsync
BattlePass	BattlePassService	GetProgressAsync, AddXpAsync, ClaimRewardAsync, PurchasePremiumAsync
Quests	QuestsService	ListAsync, ClaimAsync, ReportProgressAsync
Stores	StoresService	ListAsync, GetAsync, PurchaseAsync
Inventory	InventoryService	GetAsync
Leaderboards	LeaderboardsService	FindBySlug(slug) → handle: SubmitAsync, ListAsync
RemoteConfig	RemoteConfigService	LoadAsync, Get<T>, GetAsync<T>
Scenario	ScenarioService	TriggerAsync
Effects	EffectsService	On* effect events; complete via methods on the effect objects
Storage	StorageService	GetAsync, ListAllAsync, SaveAsync, DeleteAsync

Quests

client.Quests covers the player's global quests — list with per-objective progress, claim, and metric reports. These are distinct from scenario quest nodes, which advance through QuestEffect (Effects.OnQuest).

var quests = await client.Quests.ListAsync();
foreach (var quest in quests)
{
    if (quest.Status == "completed")
        await client.Quests.ClaimAsync(quest.Id);
}

// Custom metrics advance matching objectives server-side; the call returns
// the ids of quests completed by this report.
var completedIds = await client.Quests.ReportProgressAsync("kills", 1);

Purchase metrics are reported automatically by store purchases; QuestMetrics.PurchaseOffer(offerId) / QuestMetrics.PurchaseItem(itemId) name the format (purchase.offer:<offerId>, purchase.item:<itemId>) so quest configs and client code agree on it.

Sessions

Every API call goes through the client's session pipeline: a 401 triggers a single-flight token refresh and one transparent retry. When the refresh fails, tokens are cleared and Auth.AuthStateChanged fires with RudderAuthState.SignedOut.

Errors

Transport maps failures to typed exceptions:

• RudderAuthException — HTTP 401
• RudderNotFoundException — HTTP 404
• RudderRateLimitException — HTTP 429
• RudderNetworkException — no response (connectivity, timeout)
• RudderApiException — base class, any other status

All of them carry StatusCode (int), the machine-readable Code (see RudderErrorCodes) and the server-issued RequestId when available.

Scenario effects

The server owns scenario execution. Trigger with client.Scenario.TriggerAsync, subscribe to typed effects on client.Effects, and call client.Update every frame:

OnNotification, OnStoreOffer, OnLeaderboard, OnWait, OnQuest, OnBattlePass, OnBattlePassLevel, OnScenarioCompleted, OnScenarioFailed.

Complete an effect with the methods on the object (DoneAsync, PurchaseAsync/DeclineAsync, EndAsync/ClaimAsync, …) or the run stalls. unknown_run / run_expired drop the run and fire OnScenarioFailed.

Tests

dotnet test tests/Rudder.Core.Tests