Tracking Events

The Analytics Engine tracks user behavior: page views, game launches, payment flows, and custom UI interactions. Tracking is fire-and-forget: track() never throws, never awaits the network, and never impacts your frontend's performance.

Tracking an event

sdk.analytics.track('game_tile_click', {
  gameId: 'game_sweet_bonanza',
  position: 'row_1_col_3',
  category: 'SLOTS'
});

Event structure

type AnalyticsEventName =
  // platform-standard catalog (closed):
  | 'page_view' | 'login' | 'register'
  | 'game_launch' | 'game_tile_click'
  | 'deposit_initiated' | 'withdrawal_requested'
  | 'bonus_claimed' | 'tournament_opt_in'
  // operator-defined events use the 'custom:' prefix:
  | `custom:${string}`;

interface AnalyticsEvent {
  eventName: AnalyticsEventName;
  timestamp: string;       // auto-generated ISO-8601
  payload?: Record<string, string | number | boolean | null>; // typed passthrough, no untyped holes
  userId?: string | null;  // auto-attached when logged in
}

One platform rule governs free-form data: structures are fully typed; payload data rides inside a typed envelope as primitive passthrough: string, number, boolean, or null values only.

GIVEN a platform-standard event name (the closed catalog above)
WHEN track(name, payload) is called
THEN the event is queued with its payload, enriched with the current
     userId (null when anonymous), and flushed per the batching contract
     (see Architecture & Batching).

GIVEN an operator-defined event
WHEN it is tracked
THEN its name carries the 'custom:' prefix, so the standard catalog stays
     closed and dashboards can rely on it.

GIVEN any track() call
WHEN the queue is full or the flush timer fires
THEN events are batched and sent; a failure NEVER throws to your code;
     see Architecture & Batching for the retry-and-drop contract.

Auto-context enrichment

You never pass userId manually; the SDK is wired to the authentication module: logged-in players' events carry their user id; anonymous traffic (e.g., landing-page views) carries null, and is accepted by the backend under the anonymous-ingest policy (rate-limited, payload-capped; see Architecture & Batching).

Sandbox

Tracked events are captured in the sandbox sink and inspectable through the sandbox control:

const events = await sdk.analytics.sandbox.getReceivedEvents();
// AnalyticsEvent[]: everything flushed so far

See Sandbox Controls.