Unity SDK

Package layout

The Unity integration lives under Assets/Packages/Rudder.Unity. Runtime code exposes the Rudder singleton facade, while the example sandbox lives under Assets/LiveOpsExamples.

1. Create configuration

Create a LiveOpsConfiguration asset and fill it with the project key from the Rudder dashboard. Use production endpoints for a live build.

2. Add the scene bootstrap

Add a GameObject to your first scene, attach the Rudder component, and assign the LiveOpsConfiguration asset. The component uses DontDestroyOnLoad, restores scenario state, and calls the core client update loop every frame.

// Scene setup:
// 1. Create a GameObject named GameSetup.
// 2. Add the Rudder component.
// 3. Assign your LiveOpsConfiguration asset in the Inspector.
// 4. Put this object in the first loaded scene.

using RudderSdk.Unity;
using UnityEngine;

public sealed class LiveOpsStartupCheck : MonoBehaviour
{
    private async void Start()
    {
        if (!Rudder.IsInitialized)
        {
            Debug.LogError("Rudder component is missing or has no configuration.");
            return;
        }

        await Rudder.Auth.LoginViaDeviceAsync();
    }
}

3. Login before SDK calls

The static Rudder facade becomes available after the component initializes. Call device login once before protected SDK calls.

using RudderSdk.Unity;
using UnityEngine;

public sealed class LiveOpsLogin : MonoBehaviour
{
    private async void Start()
    {
        if (!Rudder.IsInitialized)
        {
            Debug.LogError("Rudder is not initialized.");
            return;
        }

        await Rudder.Auth.LoginViaDeviceAsync();
        Debug.Log("Rudder SDK is ready.");
    }
}

4. Remote config

Load remote config after login, then read typed values from the cache with safe defaults.

await Rudder.RemoteConfig.LoadAsync();

var difficulty = Rudder.RemoteConfig.Get("difficulty", "normal");
var enemyCount = Rudder.RemoteConfig.Get("enemy_count", 0);
var shopEnabled = Rudder.RemoteConfig.Get("shop_enabled", false);

5. Stores and leaderboards

The Unity facade exposes the same core services as the C# SDK. The sandbox example uses Rudder.Stores.ListAsync() and a leaderboard handle from Rudder.Leaderboards.FindBySlug().

var stores = await Rudder.Stores.ListAsync();
foreach (var store in stores.Stores)
{
    Debug.Log($"{store.Slug}: {store.Name}");
}

var leaderboard = Rudder.Leaderboards.FindBySlug("default");
await leaderboard.SubmitAsync(4200);
var entries = await leaderboard.ListAsync(limit: 20);

6. Scenario handlers

Register scenario handlers before triggering scenario events. Complete client-visible nodes through their session methods so the scenario runtime can continue the plan.

private void RegisterScenarioHandlers()
{
    Rudder.Scenarios.OnNotification += OnScenarioNotification;
    Rudder.Scenarios.OnStore += OnScenarioStore;
    Rudder.Scenarios.OnQuest += OnScenarioQuest;
    Rudder.Scenarios.OnRunFailed += OnScenarioRunFailed;
}

private void OnScenarioNotification(NotificationSession session)
{
    Debug.Log($"Notification node: {session.Context.NodeId}");
    session.Complete();
}

private void OnScenarioStore(StoreSession session)
{
    ShowStore(session.Id,
        onPurchase: () => session.Buy(),
        onDismiss: () => session.Decline());
}

private void OnScenarioQuest(QuestSession session)
{
    session.AddProgress("kills", 1);
}

await Rudder.Scenarios.SendAsync("player_login");

7. Realtime

Realtime uses the configured RealtimeUrl and the access token from device login. The Unity package provides native and WebGL websocket adapters behind UnityRealtimeTransportFactory.

var session = await Rudder.Realtime.ConnectAsync(timeoutSeconds: 5);

session.MessageReceived += payload =>
{
    Debug.Log($"Realtime payload: {payload.Count} bytes");
};

await session.SendAsync(BuildReadyPayload());
await Rudder.Realtime.DisconnectAsync();

Runtime lifecycle

The Rudder component calls Client.Update(Time.deltaTime) in Update(). Keep one bootstrap component alive across scenes so scenario waits, realtime transport updates, token storage, and persisted plan state stay consistent.