Data Model

Events

Events are the raw data foundation for all platform metrics. Every user interaction and system action produces events that feed into KPI computation.

General Rules

Every event includes a timestamp
Frontend-triggered events use the client timestamp
Backend-triggered events use the server timestamp

Event Catalog

Event	Trigger	Source	Description
`game_impression`	A game card is displayed in a list	Backend	Can be batched. Fired for Home, category, and recommendation lists
`game_click`	User clicks a game card in a list	Frontend
`game_page_view`	A game’s detail page is opened	Backend
`category_click`	User clicks a category	Frontend

2. Game Loading

Event	Trigger	Source	Description
`game_loading_start`	Game iframe begins loading	Frontend
`game_loading_end`	Game is fully loaded and playable	Frontend	Used with `game_loading_start` to compute loading time

3. Focus & Visibility

Event	Trigger	Source	Description
`game_focused_start`	Game receives focus (tab visible, iframe active)	Frontend
`game_focused_stop`	Game loses focus (tab hidden, user switches away)	Frontend

4. Gameplay

Event	Trigger	Source	Description
`gameplay_start`	Gameplay begins	Frontend	Intercepted from GameDistribution SDK. Future games will use a Playupi SDK
`gameplay_stop`	Gameplay ends	Frontend	Used to compute session count and duration

5. Monetization

Event	Trigger	Source	Description
`show_ad`	An ad is displayed during gameplay	Frontend

6. Feedback

Event	Trigger	Source	Description
`game_like`	User likes a game	Frontend	Tracked via `POST /api/v1/games/:id/like`, not via the event ingestion endpoint
`game_dislike`	User dislikes a game	Frontend	Tracked via `POST /api/v1/games/:id/dislike`, not via the event ingestion endpoint

Note: Like/dislike actions use dedicated feedback endpoints (see API Reference) and are stored in the GameFeedback table, not in the raw events table. The likes/dislikes counters on the Game model and DailyMetric table are updated accordingly.

Metrics & KPIs

All metrics are computed over a time range (minimum granularity: 1 day).

Metrics can be segmented by platform (desktop / mobile).

Display modes:

Cumulative: total over the period
Average: mean per day or per player over the period

1. Engagement Metrics

Metric	Definition	Display
Plays	Number of game sessions started. Counted from the first `gameplay_start` after a game loads	Cumulative, daily average
DAU (Daily Active Users)	Unique users who played per day per game	Cumulative over period, daily average
Impressions	Number of times a game card was shown in a list. Based on `game_impression`	Cumulative, average
CTR (Click-Through Rate)	`game_click / game_impression`	Percentage

2. Performance Metrics

Metric	Definition	Display
Playtime	Average time spent playing. Computed only when: game is loaded, game is focused, gameplay is active. Uses all loading/focus/gameplay events ordered by timestamp	Average per player
Engaged Players	% of players with playtime >= 3 minutes. `players_with_playtime_>=_3min / total_players`	Percentage
Conversion	% of page visitors who reach a loaded game. `game_loading_end / game_page_view`	Percentage
Retention D1	% of players who replay the same game the next day. `active_day_J_AND_J+1 / active_day_J`	Percentage
Retention D7	% of players who replay within 7 days. `active_day_J_AND_any_day_J+1_to_J+7 / active_day_J`	Percentage
Returning Users	% of players who played the game before the analysis period	Percentage
Rating	Score from likes and dislikes. `like = +1, dislike = -1`. Exact formula may evolve	Score
Loading Time	Average load duration. `game_loading_end - game_loading_start`	Duration (seconds)

3. Monetization Metrics

Metric	Definition	Display
Ads Shown	Number of ads displayed. Based on `show_ad`	Cumulative, average per session/player

4. Future Metrics (not in MVP)

Metric	Definition
Crash Rate	% of sessions ending abnormally (no `gameplay_stop`, frontend-detected crash)
Mean FPS	Average FPS during gameplay, measured via canvas/WebGL if technically feasible

Playtime Computation

Playtime is the most complex metric — it requires reconstructing a session timeline from loading, focus, and gameplay events to compute active play time (excluding unfocused or loading periods).

See Events Pipeline → Playtime Computation for the full algorithm and edge case handling.

Tag	Rule	Notes
New	Game added less than 14 days ago	Indicates recency only. Can be New + Ranked or New + Unranked
Trendy	DAU over last 7 days > DAU from day -14 to day -7	Indicates momentum, not absolute popularity. Computed per platform/category
Updated	Game or live build updated less than 7 days ago	Planned, not enabled in MVP