Types & Data Structures

All types can be imported directly from the module’s Types submodule:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Types = require(ReplicatedStorage.AnalyticsModule.Types)

---

Core Telemetry Types

EventCategory

Defines the high-level classification of an event:

export type EventCategory =
    | "session"
    | "server"
    | "badge"
    | "economy"
    | "error"
    | "custom"
    | "performance"
    | "retention"
    | "demographics"
    | "spatial"

---

TelemetryEvent

The standard envelope structure for all telemetry events processed by the pipeline:

export type TelemetryEvent = {
    name: string,
    category: EventCategory,
    timestamp: number,
    userId: number?,
    sessionId: string?,
    data: { [string]: any },
}

Field	Type	Description
name	string	The event identifier (e.g. "SessionStart", "PlayerDeath", "BossDefeated").
category	EventCategory	Event category classification.
timestamp	number	Unix epoch timestamp (seconds) when the event occurred.
userId	number?	Associated Roblox UserId, or nil for server-wide events.
sessionId	string?	GUID string identifying the player’s active session.
data	{ [string]: any }	Payload dictionary containing event-specific parameters.

---

Session & Retention Types

SessionData

Represents the active state of an in-game player session:

export type SessionData = {
    userId: number,
    sessionId: string,
    joinTime: number,
    leaveTime: number?,
    duration: number?,
    activeDuration: number?,
    totalIdleTime: number,
    isAfk: boolean,
    lastActivityTime: number,
    platform: string?,
    locale: string?,
}

---

RetentionRecord

Persistent DataStore record tracking player return cohorts:

export type RetentionRecord = {
    firstJoinTime: number,
    lastJoinTime: number,
    totalVisits: number,
    totalPlaytimeSeconds: number,
    milestonesClaimed: { [string]: boolean },
}

---

Diagnostics & Hardware Types

ServerHealthSnapshot

Diagnostics telemetry generated periodically by ServerTracker:

export type ServerHealthSnapshot = {
    serverJobId: string,
    placeId: number,
    placeVersion: number,
    uptimeSeconds: number,
    playerCount: number,
    peakPlayerCount: number,
    memoryUsageMb: number,
    averageHeartbeatFps: number,
    timestamp: number,
}

---

ClientDemographics

Client hardware, resolution, and locale captured by the Client SDK on join:

export type ClientDemographics = {
    platform: "PC" | "Mobile" | "Tablet" | "Console" | "VR" | "Unknown",
    inputDevice: "KeyboardMouse" | "Touch" | "Gamepad" | "VR" | "Unknown",
    viewportWidth: number,
    viewportHeight: number,
    networkPingMs: number,
    locale: string,
    accountAgeDays: number,
}

---

SpatialCoordinates

3D vector coordinates rounded to 1 decimal place:

export type SpatialCoordinates = {
    x: number,
    y: number,
    z: number,
}

---

Pipeline & Extensibility Types

IExporter

Interface contract required for all telemetry exporters:

export type IExporter = {
    name: string,
    exportBatch: (events: { TelemetryEvent }) -> (boolean, string?),
    flush: () -> (),
}

---

MiddlewareFn

Transformation or filter callback invoked before an event enters the buffer queue. Return nil to drop the event:

export type MiddlewareFn = (event: TelemetryEvent) -> TelemetryEvent?