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¶
- Log in with username or email + password (accounts via admin
Users or
POST /api/auth/register). The API key is stored inlocalStorage. Profile load readsfollow_limits_enabledandleague_follow_quotas, and syncs browser IANAmatch_follow_timezonewhen it differs. - The page opens
WS /api/play/stream, appliessnapshot/question.opened/question.closed, and submits answers with BearerPUT /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 markedis_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 onquestion.openedand a different tone onquestion.closedwithreason=resolved(not on reconnectsnapshot, lock republish, retracts, or stale closes). Sounds are off by default; Turn sound on/off in the header toggles this and persists inlocalStorage. Turn situation on/off sits beside it. Situation lines are on by default; turning them off closesWS /api/play/situationand hides the situation sidebar. That choice persists inlocalStorage. The question socket stays open. Recently Resolved opens from a header link beside Change. - 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 livequestion.opened. The Choose-matches modal lists today’s matches only (calendar day in the user’smatch_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. - Limits on (
follow_limits_enabled): must choose matches viaPOST/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. - 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 …/followand rewritelocalStorage. If unfollow gets “not following”, the checkbox clears instead of staying stuck. Clone-and-listen also appends the new id tolocalStorageimmediately. - 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).
- 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.
- 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 /openpoll 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¶
/playis 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.