Dashboard

Sending events

Automatic events, your own milestones, stages, devices and flushing.

Last updated Oct 9, 2026

Automatic events

EventWhenIncludes
session_startedA player joins-
player_diedA character diesPosition of the HumanoidRootPart
player_quitA player leavesLast known position
session_endedA player leavesdurationSeconds in metadata

Your own events

Luau
analytics:track(player, "stage_completed", {
	stageId = "stage_3",
	position = true,                 -- or a Vector3
	metadata = { seconds = 41, attempts = 3 },
})

analytics:setStage(player, "stage_4") -- default stageId for this player's later events
analytics:startFunnel(player, "tutorial") -- puts this player in the funnel with key "tutorial"
analytics:logFunnelStep(player, "tutorial", 1, "Joined") -- or: Roblox-style numbered step, no start call
analytics:track(player, "player_progress", { metadata = { cash = 1500, rebirths = 2, playtime = 3600 } })
-- Devices are detected for you. Only call this if you turned detection off:
analytics:setDevice(player, "touch")  -- keyboard | touch | gamepad | vr | unknown

Funnels start only when you say so. startFunnel(player, key) puts a player in the dashboard funnel with that key; nothing else does. Call it when your game knows the player should be measured, for example a new player reaching the tutorial. It sends one small event per player, key and session, and repeat calls send nothing.

Or log steps Roblox-style. logFunnelStep(player, key, step, name) works like Roblox's LogFunnelStepEvent: log steps 1, 2, 3… and the funnel appears in Funnels by itself, with steps in number order and labelled by name. A session enters at step 1, so log steps only for players you want measured, for example new players. Each step is sent once per player and session. A funnel can have up to 25 steps.

Player progress. Send a player_progress event with the player's own numbers as metadata (cash, rebirths, rolls, tutorial step…) when their data loads and every few minutes, and the Players tab shows a Player progress card: median, middle half, top 10% and highest of each value, using each player's latest snapshot in the range, plus a per-value breakdown for small whole numbers such as rebirths. playtime and keys ending in Seconds are shown as durations. One snapshot every two minutes is a few bytes a minute after gzip.

position = true samples the player's character. Positions are Roblox studs with no axis conversion, rounded to 0.01. Send positions on meaningful events such as deaths and checkpoints, not on a timer.

Devices are detected automatically. The server cannot see a player's device, so the SDK copies a small client script into StarterPlayerScripts that reports touch, keyboard, gamepad or vr over a RemoteEvent called RoStructureDevice in ReplicatedStorage. It updates if the player switches input, for example plugging in a controller. Events recorded after the report carry the device, so deaths and funnels can be split by it.

Purchases and revenue (optional)

Revenue tracking is off unless you turn it on. Both switches must be on: revenue = true in RoStructure.init, and Settings → Revenue for the project. If only the SDK switch is on, the API discards the amounts.

With revenue = true the SDK records purchases for you. You do not change your purchase code.

It never touches your receipt handling

Roblox lets a game set one ProcessReceipt callback, and the newer MarketplaceService:BindReceiptHandler registers handlers that return the decision telling Roblox a purchase was granted. A library that took either could stop your game from granting what players paid for, so the SDK does neither. Your ProcessReceipt, your bound handlers and your granting code run exactly as before.

Instead it listens to the events Roblox fires when a purchase prompt finishes (PromptProductPurchaseFinished and PromptGamePassPurchaseFinished). Listening cannot change what your game does, and a failure in the SDK cannot reach your handlers.

Exact amounts (optional)

If you need the exact amount, call trackReceipt at the top of your own receipt handler and turn off the automatic recording so nothing is counted twice:

Luau
local analytics = RoStructure.init({
	projectId = "proj_...", ingestionKey = KEY,
	revenue = true,
	revenueAuto = false,        -- you report receipts yourself
})

MarketplaceService.ProcessReceipt = function(receiptInfo)
	analytics:trackReceipt(receiptInfo)   -- reads the receipt; does not yield or return anything
	-- ...your existing purchase handling, unchanged...
end

trackReceipt records each PurchaseId once and only counts Robux purchases. It never returns a purchase decision, so what your handler returns is up to you.

Flushing and stats

Luau
analytics:flush()        -- yields; sends what is queued
print(analytics:stats()) -- queued, inFlight, requests, sentEvents, droppedEvents, retries

On server shutdown the SDK ends open sessions and flushes for up to 20 seconds automatically.