Skip to content

Live (Play)

Public Live page for answering open questions. Open questions are delivered over WebSocket; answers stay on REST.

URL /play (also linked from admin nav; opens in a new tab)
Stream WS /api/play/stream?api_key= (questions) · WS /api/play/situation?api_key= (optional current-situation lines)
REST POST /api/auth/login · GET/PATCH /api/users/me · POST/DELETE /api/matches/{id}/follow · PUT /api/question-answers · GET /api/question-answers · GET /api/matches (today’s slate for Following, optional followed=true) · GET /api/users/me/points · GET /api/question-answers/open (catch-up only)

Mobile / client authors: Live play client.

Workflow

  1. Log in with username or email + password (accounts via admin Users or POST /api/auth/register). The API key is stored in localStorage. Profile load reads follow_limits_enabled and league_follow_quotas, and syncs browser IANA match_follow_timezone when it differs.
  2. The page opens WS /api/play/stream, applies snapshot / question.opened / question.closed, and submits answers with Bearer PUT /api/question-answers. Open questions are the primary UI: countdown and prompt first, then a situation / clock / period line when the issuing event had that context, then large choice buttons; a Pivotal badge when the definition was marked is_pivotal_moment; a Match question badge for pre-game Match questions; sponsors and issuance IDs sit below. When a match or question sponsor is unset, Live shows the Parlay Rewards brand in that slot (display only; stored sponsors stay empty). With multiple open questions, unanswered questions stay on top; answering one sinks that question below the others (still changeable until the window closes, or until the match starts for Match questions). A question that can no longer be changed stays on the column as Pending and sinks below anything still answerable. In-game Pending (countdown elapsed) stays above answered locked Match questions, which sit at the bottom of that group. A locked Match question with no selection leaves the column. On close, an answered question leaves the column and shows under Recently Resolved, newest close first, so a Match question answered before the game still appears when it closes. An unplayed Match question has no answer, so it does not appear there. Lock republish does not play the issue tone. Live plays a short browser tone on question.opened and a different tone on question.closed with reason=resolved (not on reconnect snapshot, lock republish, retracts, or stale closes). Sounds are off by default; Turn sound on/off in the header toggles this and persists in localStorage. Turn situation on/off sits beside it. Situation lines are on by default; turning them off closes WS /api/play/situation and hides the situation sidebar. That choice persists in localStorage. The question socket stays open. Recently Resolved opens from a header link beside Change.
  3. Following: the bar lists each followed match as a label with (questions/pivotal) issuance totals from the match list (e.g. NYY @ CHC (7/3) = 7 non-pivotal questions issued, 3 pivotal moments — mutually exclusive; hover shows the match shortcode after a short delay). The situation sidebar lists each followed match that has a live line (situation · clock · period, score in the title). The row is replaced in place and stays when no question is open. Matches that have not produced a line yet are omitted. Question cards keep the situation frozen at issue time. Counts refresh with the followable slate poll and bump on live question.opened. The Choose-matches modal lists today’s matches only (calendar day in the user’s match_follow_timezone; all statuses), grouped by league, with the same (questions/pivotal) counts and shortcode in each row. Each league header shows how many follows are left today when daily follow limits are on. Follows for other days stay on the server but are hidden from the bar/modal until that day’s slate.
  4. Limits on (follow_limits_enabled): must choose matches via POST/DELETE …/follow; empty selection shows no questions. Each league has its own daily cap. Unfollow before start refunds that league's slot; unfollow after start (non-test) does not. Test matches never count and always refund.
  5. Limits off: must still follow matches to see live questions (empty selection shows none); no daily quota. Each league header has All / None for bulk select. On login the local list is replaced with server follows (clone auto-follow is already stored on the server), then pruned to today’s slate. Toggle / clear / league bulk also sync POST/DELETE …/follow and rewrite localStorage. If unfollow gets “not following”, the checkbox clears instead of staying stuck. Clone-and-listen also appends the new id to localStorage immediately.
  6. Closed matches cannot be newly followed (checkbox disabled; All skips them). Matches already followed before close stay selected and may be unfollowed (no quota refund).
  7. Following a non-test in progress match asks for confirmation: unfollowing later will not refund the daily follow slot (same as server rules). Unfollow after start asks again before dropping the follow.
  8. Points and Recently Resolved refresh on a slower REST cadence (and after closes). If the socket drops, the page reconnects and falls back to a slow GET /open poll until the stream is healthy again.

Layout: mobile-first — compact header/Following, questions in a single column. Recently Resolved is a modal. When situation lines are on, that panel sits above the questions on small screens and in a sticky sidebar from ~900px. Turning situation off hides the sidebar so questions use the full width.

Recently Resolved cards (shared admin_answer_history_list) show Answered and, once scored, Actual (the winning choice) on the same line, plus match label, shortcode, a short issuance id (first 8 of question_issuance_id) with a copy button for the full UUID, and answered-at. Expand for the full issuance id (also copyable), definition id, sponsors, and event/condition details.

Report this: on a resolved outcome, a logged-in player can file user feedback. Pending questions stay on the question column until they close, so they are not in this list. The modal asks for a Topic (from GET /api/user-feedback/form for that row’s kind) and an optional description (max 250 characters). One submission per answer. After a successful POST (or a 409 already submitted), the control becomes a quiet Feedback sent. History offers the same control for operators reviewing a player. Mobile contract: Report this. Operators review submissions on User Feedback.

Notes

  • /play is outside /admin (no admin session required).
  • If the stored Bearer key returns Invalid or revoked API key, Play clears the local session (same as Change) and shows the login form again.
  • Admin operators sign in at /admin/login; Manage → Users creates accounts.
  • Ops (cache TTL, WS connection caps, Caddy/ALB path routing): Environment configuration.