Unity SDK · Analytics

Send gameplay events with one line. Sessions, DAU/MAU, retention and per-event breakdowns light up automatically on the dashboard. Batched up to 50 events or flushed every 30 seconds; offline-safe.

Overview

KalmForge.Analytics is a static class. As soon as KalmForgeClient.Init() resolves, a session is started automatically and ended on app quit / pause. You don't need to wire anything up to start collecting DAU, retention, sessions and event counts.

Quick start

LevelComplete.csC#

1using KalmForge;
2
3public class LevelComplete {
4    public void Run(int level, int score) {
5        Analytics.TrackEvent("level_complete");
6        Analytics.TrackEvent("level_complete", level.ToString());
7        Analytics.TrackEvent("level_complete", "win", new System.Collections.Generic.Dictionary<string, object> {
8            { "level", level },
9            { "score", score },
10            { "duration_s", 124.5 },
11        });
12    }
13}

Tracking events

TrackEvent(name) with an optional label and properties dictionary. The dashboard groups by name.label, so labels become first-class rows in the events table.

exampleC#

1Analytics.TrackEvent("ad_watched");
2Analytics.TrackEvent("ad_watched", "extra_life");          // → "ad_watched.extra_life"
3Analytics.TrackEvent("purchase", "coin_pack_small",
4    new Dictionary<string, object> { { "price", 0.99 } });

Event naming rules

Event names (and labels) are sanitised before sending: only a-z A-Z 0-9 _ . - survive; everything else becomes _. The result is truncated to 64 characters.

Tip

Stick to lowercase snake_case with a stable, finite vocabulary (e.g. level_complete, shop_open, iap_purchase) so dashboards stay aggregable.

Properties & bandwidth

Properties are recorded for size only - the dashboard counts the event as units = 1 and adds the JSON byte size to your project's bandwidth bar. You don't currently filter on property values from the dashboard, so use them for context (or build your own pipeline against the REST endpoint).

Sessions

Sessions are bracketed by OnInitialized and OnShutdown on KalmForgeClient:

Start: POST /api/public/sdk/session with action: "start" → server returns a session_id.
End: POST with action: "end", session_id, duration_seconds.
Pausing the app to background also flushes pending events and ends the session.

Batching

Events are buffered in memory and flushed when any of these is true:

Batch size hits 50 events.
The 30-second timer ticks (a hidden MonoBehaviour handles this for you).
The session ends (app quit / pause / background).

Heads up

If the network call fails the events stay buffered for the next flush. Power-loss on a long offline session can drop events; treat Analytics as best-effort, not bookkeeping.

API reference

Analytics - static API

Name	Type	Description
TrackEvent(name, label?, properties?)	void	Queue an event. Drops with a warning if name is empty or analytics is disabled.

Disable analytics for a single build by toggling KalmForgeSettings.AnalyticsEnabled = false. The capability flag KalmForgeCapabilities.Analytics is server-controlled per-plan.

REST endpoint

examplebash

1# Track a batch of events
2POST /api/public/sdk/track
3Headers: X-API-Key: kf_xxx_yyy
4{
5  "sdk_version": "1.0.1",
6  "platform":    "WindowsPlayer",
7  "install_id":  "...",
8  "player_id":   "...",
9  "events": [
10    { "event_type": "level_complete.win", "units": 1, "bytes": 42, "occurred_at": "2026-05-02T12:00:00Z" }
11  ]
12}
13
14# Session lifecycle
15POST /api/public/sdk/session
16{ "action": "start", "install_id": "...", "platform": "...", "sdk_version": "1.0.1", "player_id": "..." }
17→ { "session_id": "..." }
18
19POST /api/public/sdk/session
20{ "action": "end", "install_id": "...", "session_id": "...", "duration_seconds": 312 }