Stat-Dashboard/mockups/METRICS.md

# Metric definitions

The sample calculates metrics under an internal `game_id`, using UTC calendar days. The selected 14-day range, for example, includes today and the previous 13 days. Today's data is partial. All records are synthetic. Recents tables show the latest stored records; their captions state their limits.

Unknown source values stay `NULL` in the API and display as `N/A`. An empty known count is zero. Ratios with zero denominators are `N/A`. Missing durations are excluded from duration averages, rather than treated as zero. Snapshot values are game-reported; session and sales aggregates are derived from their own stored records.

## Activity and sessions

| Measurement | Definition |
| --- | --- |
| CCU | Latest game-level concurrent-player report. A missing latest report remains N/A; the chart averages available reported samples per day. |
| Visits | Sum of game-level daily visit reports in the selected range. The sample generates these from session starts, counting repeat visits. |
| DAU | Distinct players with a session overlapping the UTC day, a player event on that day, or a sale attributed to them on that day. An unended session only proves activity on its start day. |
| Calculated MAU per day | Distinct active players across the 30 calendar days ending on each graph day, inclusive. It is recalculated for every day, not a monthly total copied across days. |
| New users | Daily active players whose first-seen UTC date is that day. |
| Returning users | Daily active players first seen before that day. New + returning = DAU. |
| Session count | Number of sessions starting in the selected period, including unended sessions. |
| Total playtime | Known completed-session time overlapping the selected days. Sessions crossing midnight are split between days. Unknown end times contribute no invented duration. |
| Average playtime | Known completed playtime divided by unique active players in the period. The daily graph divides each day's playtime by that day's DAU. |
| Average session time | Average duration of completed sessions starting in the period. Median is also shown. |
| New-user session time | Average completed-session duration for sessions starting on the player's first-seen UTC day. |
| Returning-user session time | Average completed-session duration for sessions starting on a later UTC day. |
| First-session five-minute retention | Players whose first completed-known session lasted at least 300 seconds / players with a known end for their first session in the selected cohort window. Missing first-session end times are excluded from the denominator, not counted as failures. |
| Day 1 / Day 7 retention | Share of players returning on the exact UTC day 1 or day 7 after their first session. Only cohorts in the selected period with a full observation day are eligible. Cohort percentages are weighted by player count. |
| Activity run time | Configured activity start to configured activity end. Activity pages aggregate runs; individual runs are available in player info. Incomplete runs show N/A time/outcome. |

## Monetization

Each sale row records its product, price **at sale time**, quantity, receipt identifier, time, and player/session when known. `(game_id, receipt_id)` is unique. The real Roblox ModuleScript integration should report trusted server-side receipt data; sample seeding only demonstrates this storage contract. No live Roblox product catalog fetch or real sale ingestion is implemented yet.

| Measurement | Definition |
| --- | --- |
| Hourly / daily Robux spent | Sum of reported unit price × quantity per UTC hour/day. These are gross reported Robux, not a conversion to cash or net proceeds. |
| Robux per product | Sum of actual reported sale prices × quantities for that product in the selected period. Current catalog price is displayed separately. |
| Paying users | Distinct players with at least one positive-price sale in the selected period. Free claims do not create payers. |
| Payer conversion | Period paying users / unique period active users × 100. The daily graph uses daily payers / DAU. |
| Average Robux per paying user (ARPPU) | Period Robux spent / distinct period paying users. |
| Average products bought per paying user | Total positive-price product units / all distinct period paying users. Decimal values are intentional. |
| Per-product units per paying user | That product's paid units / **all** period paying users, including payers who did not buy that particular product. Every catalog product is listed. |
| ARPDAU / average Robux per daily active user | These are the same measurement: daily Robux / DAU. The period card uses total period Robux / sum of daily active user counts (user-days), which is the weighted daily average. It does not divide by unique period players. |
| Sales / transactions | Count of unique reported receipts, including zero-price records. |
| Unattributed sales | Positive-price reports with no player ID. Total Robux remains known, but payer ratios become N/A when attribution is incomplete. |

## Gamepass ownership and activity stages

The Monetization page has Revenue and Gamepasses tabs. Gamepass ownership uses explicit per-player true/false observations, independent of purchase reports. The all-player percentage divides owners by all tracked players in this game. The paying-player percentage divides paying owners by lifetime players with a recorded positive-price purchase. An incomplete set of ownership checks displays N/A for the affected percentage; reporting coverage is displayed separately. No paying players means N/A for the paying-player percentage. These ownership percentages are current snapshots and do not use the selected revenue date range.

Activity stages use ordered `stage_progress` event observations. Stage reach is the percentage of all activity starts reaching that stage in sequence. Conversion divides stage reach count by the previous stage count; drop-off is its complement. A later event does not count if a required earlier stage was skipped. Unknown stage observations make subsequent percentages N/A rather than fabricated drop-offs.

Events show one daily graph line and one summary row per event name. Global recent-event, recent-session, and recent-sale tables are removed; individual records remain in player info. Game-root metric categories remain stored but have no overview or project-settings table. Session aggregates and charts accept the same player groups as activity analytics.

## Player group defaults

Player history accepts `value` and optional `value2` and plots them at stored snapshot timestamps with independent left/right scales. Numeric custom snapshot fields are discoverable. Derived session and receipt totals use only records at or before that timestamp; incomplete durations remain N/A. Join session is a UI placeholder enabled only for unended sessions started within the past six hours. This age rule is a mockup heuristic, not confirmation that a Roblox server is still joinable.

The Events chart filters lines using a searchable checkbox picker with All/None controls. Selection is stored locally per internal game ID. Hidden series are excluded from hover tooltips and axis scaling, while summary totals remain unchanged.

Whales are the top 20% of players with known positive lifetime recorded Robux spending. Top playtime is the top 20% with known positive completed-session playtime. First-time players were first seen in the last 24 hours. These are sample group definitions, not fixed business rules; the intended product should allow configurable thresholds and periods.