first

docs/analytics-taxonomy.md

@@ -0,0 +1,106 @@
+# Analytics Taxonomy
+
+## Rules
+
+- All analytics events are structured
+- No JSONB payloads
+- Events live in `analytics_events`
+- Attributes live in `analytics_event_attributes`
+
+## Event Groups
+
+### Lifecycle
+
+- `app_opened`
+- `app_backgrounded`
+- `app_closed`
+- `session_started`
+- `session_ended`
+
+### Onboarding
+
+- `language_selected`
+- `consent_viewed`
+- `consent_accepted`
+
+### Feed and Round Load
+
+- `feed_viewed`
+- `round_card_viewed`
+- `round_loaded`
+- `event_manifest_received`
+- `preview_prefetch_started`
+- `preview_prefetch_completed`
+
+### Playback
+
+- `preview_started`
+- `preview_paused`
+- `preview_resumed`
+- `preview_completed`
+- `reveal_started`
+- `reveal_completed`
+- `playback_error`
+- `stream_reconnected`
+
+### Timing and Odds
+
+- `countdown_visible`
+- `countdown_warning_threshold_hit`
+- `odds_panel_viewed`
+- `odds_version_received`
+- `odds_changed`
+
+### Selection and Settlement
+
+- `outcome_focused`
+- `outcome_selected`
+- `selection_submitted`
+- `selection_accepted`
+- `selection_rejected`
+- `duplicate_selection_attempt`
+- `market_locked`
+- `result_viewed`
+- `next_round_requested`
+
+### UI and Input
+
+- `screen_viewed`
+- `cta_pressed`
+- `gesture_swipe`
+- `gesture_tap`
+- `gesture_cancelled`
+- `haptic_triggered`
+
+### Localization and Errors
+
+- `localization_bundle_loaded`
+- `locale_changed`
+- `network_error`
+
+## Common Attributes
+
+- `screen_name`
+- `event_id`
+- `market_id`
+- `outcome_id`
+- `odds_version_id`
+- `countdown_ms_remaining`
+- `locale_code`
+- `experiment_variant`
+- `network_type`
+- `device_orientation`
+- `playback_position_ms`
+- `latency_ms`
+
+## Research Metrics
+
+- Decision latency
+- Round completion rate
+- Missed rounds
+- Post-lock selection attempts
+- Replay desire
+- Exit rate
+- Control vs modern comparison
+- Locale effects
+- Device platform effects