C# SDK Integration Guide (Unity / Godot / .NET)

GoWind UBA's C# data collection SDK is for Unity (native + WebGL), Godot 4 (.NET), and .NET consoles/services, reporting user behavior and risk events to the Collector service.

Applies to: event tracking in games / clients. For web pages, use the Web SDK. Source code: sdk/csharp/.

1. Capability Overview

• Zero-NuGet-dependency core library (Uba.Core, .NET Standard 2.0, hand-written camelCase JSON serializer).
• Application-level authentication: appId + appSecret in the request body, no token needed.
• Batch reporting + retry degradation, consistent with the Web SDK's behavior.
• High-level API: Track / TrackRisk / Identify / SetSuperProperties / FlushAsync.
• Pluggable Transport / ContextProvider: supports self-built gateways, signing, and custom device identifiers.

2. Structure

sdk/csharp/src/
├── Uba.Core/          # .NET Standard 2.0 core library (zero dependencies)
│   ├── Client.cs      # UbaClient + high-level API + IContextProvider
│   ├── Batcher.cs     # batch buffering
│   ├── Transport.cs   # IHttpTransport + HttpClientTransport (default)
│   ├── Config.cs      # UbaConfig + TrackOptions
│   ├── Types.cs / Json.cs / Utils.cs
├── Uba.Unity/         # Unity adapter (references UnityEngine)
│   ├── UnityWebRequestTransport.cs   # required for WebGL
│   ├── UnityContextProvider.cs       # SystemInfo device/platform detection
│   └── UbaUnityBehaviour.cs          # convenience MonoBehaviour component

3. Platform & Transport Matrix

⚠️ Unity WebGL must use UnityWebRequestTransport: HttpClient is unavailable on the WebGL platform and throws.

4. Building

cd sdk/csharp/src/Uba.Core
dotnet build -c Release
# artifact: bin/Release/netstandard2.0/Uba.Core.dll

Uba.Unity needs to be compiled inside Unity, or built by pointing the UnityAssemblies environment variable at Unity's Managed/UnityEngine.dll.

5. Using in Unity

Option A: convenience component (recommended)

1. Copy Uba.Core.dll into Unity's Assets/Plugins/.
2. Copy Uba.Unity/*.cs into Assets/Scripts/Uba/.
3. Create an empty GameObject in the scene, attach UbaUnityBehaviour, and configure endpoint / appId / appSecret.
4. Call:

using Uba.Unity;

UbaUnityBehaviour.Track("level_finish", new() { ["level"] = "1-1" },
    new TrackOptions { Score = 100, DurationMs = 45000 });

UbaUnityBehaviour.Identify(1001);
UbaUnityBehaviour.Track("purchase", new() { ["orderId"] = "ORD-001" },
    new TrackOptions { Amount = "99.90", Quantity = 1 });

Option B: manual initialization

using Uba;
using Uba.Unity;

var client = new UbaClient(
    new UbaConfig {
        AppId = "your_app_id",
        AppSecret = "your_app_secret",
        Endpoint = "http://localhost:5700",
    },
    new UnityWebRequestTransport(monoBehaviour),   // note: the ctor needs a MonoBehaviour (coroutines)
    new UnityContextProvider()
);

6. Using in Godot 4

using Uba;

var client = new UbaClient(new UbaConfig {
    AppId = "your_app_id",
    AppSecret = "your_app_secret",
    Endpoint = "http://localhost:5700",
});
// Uses HttpClientTransport + DefaultContextProvider by default

client.Track("scene_load", new() { ["scene"] = "Main" });

7. API Overview (UbaClient)

UbaConfig

Timeout defaults to 8 seconds (must be < the server's 10 seconds).

TrackOptions (game dimension fields)

The third argument of Track/TrackBehavior; besides the existing business metric fields (Amount/Quantity/Score/DurationMs etc.), two new game-specific dimensions were added to support game models such as merged-server retention / level analysis:

Once set, the SDK writes them into both the top-level ReportEvent and the behavior payload (C# properties are PascalCase, serialized to camelCase JSON; level is serialized as an integer). Example:

// A player on server 5, currently level 32, finishes a level
client.Track("level_finish",
    new() { ["chapter"] = "1-1" },
    new TrackOptions { ServerId = "5", Level = 32, Score = 100, DurationMs = 45000 });

These two fields land in the server_id (VARCHAR) and level (SMALLINT) columns of the events_fact table, and are used directly by game analysis models such as ServerRetention / LevelAnalysis.

8. Auto-Completed Fields (vary by platform)

The SDK auto-completes (no business setup needed); the C# side has no autotrack automatic event tracking (unlike the Web SDK, where only Web has click auto-collection), so all events must be explicitly Tracked:

⚠️ Godot's deviceId is process-scoped: it changes after restart. If a stable device identifier is needed, persist it yourself (e.g. in a config file) and inject it via SetSuperProperties or a custom IContextProvider. ⚠️ C# unload fallback: only the Web SDK has sendBeacon; on the C# side, call FlushAsync() in OnApplicationQuit / OnDestroy to guarantee the last batch is not lost.

9. Reporting Protocol Contract

Integrates with the collector's unified interface POST /uba/v1/report, exactly like the Web SDK:

• appId + appSecret go in the request body (not headers); no retry on 401.
• Field naming is always camelCase (aligned with the backend proto contract).
• tenantId is not reported; the server authoritatively overrides it based on appId.
• Required: eventId / eventName / eventTime + one oneof payload (behavior / risk).

For the complete set of event fields, see Backend API Contract · Report Service.

10. Advanced: Custom Transport / ContextProvider

The core library abstracts via IHttpTransport and IContextProvider, allowing custom implementations to be injected:

// Custom transport (e.g. via the game gateway, with signing, or through a local relay)
public class MyTransport : IHttpTransport {
    public Task<HttpResponse> SendAsync(string url, string body, CancellationToken ct) {
        // add signature headers, route through your own gateway, etc.
    }
}

// Custom context (injecting a business-side deviceId/channel)
public class MyContext : IContextProvider {
    public DeviceContext Get() => new() {
        DeviceId = MyGame.GetPersistentDeviceId(),
        Platform = "android",
    };
}

var client = new UbaClient(config, new MyTransport(), new MyContext());

11. Integration & Troubleshooting

# Start the local collector (listens on 5700 by default)
cd backend
go run ./app/collector/service/cmd/server/ -c ./app/collector/service/configs

12. Related Documentation

• Product Introduction
• Web SDK Integration
• Backend API Contract · Report Service
• System Architecture