Live updates
The Quickstart client follows a game in two short files. This page adds what a production client needs. It shows how to keep a game’s current state, then gives four rules for staying connected. Each rule is a small change to the quickstart’s follow.mts, and the last section has the whole client with all four. The Developer plan has no stream, so on Developer, skip to Without the stream.
How the stream works
Each stream is a journal of changes. There are two kinds:
game:<game id>carries one game. That covers the game, its live state, plays, drives, game roster and player stats.league:<alias>carries what the league’s games share. That covers teams, players, venues, seasons and weeks, plus rosters, injuries, transactions and depth charts.
Every change has a seq. Within a stream, seqs have no gaps and arrive in order, so a client that has applied seq N has applied everything before it. Every change also carries the entity’s full current state. An upsert replaces what you hold under entity_type and entity_id, and a delete removes it.
A subscription starts in one of three ways:
The quickstart resumes from a REST read. One request returns the game’s current state and the seq to stream from. This works for game streams. For a league stream, subscribe with a snapshot.
Keep state
Every change carries the entity’s full state, so a map keyed by type and id holds everything a client needs. Use this onChange in place of the quickstart’s, and read from state when you render:
Fill the map from the REST read before you subscribe. The game read returns the game, its live state and both teams. The plays, drives, roster and box score endpoints return the rest. Build a scoreboard shows which entity_id each one uses.
Applying the same change twice leaves the same state, so a repeated change after a reconnect is harmless.
Stay connected
Connections drop during deploys, on mobile networks and when laptops sleep. The quickstart already resumes from the last seq it applied. These four rules cover the remaining failures.
Back off between reconnects
During an outage, a client that reconnects every second sends a failed attempt every second until the outage ends. Wait about a second after the first failure and double the wait after each failure, up to 30 seconds. Add random jitter so that many clients don’t reconnect at the same moment. Reset the count when a subscription succeeds:
Notice a dead connection
A connection can stop delivering messages without the socket closing, for example when a laptop sleeps or a router drops the route. The server sends heartbeat every 5 seconds, and can pause it for up to 10 seconds while it waits for a ping reply. If 20 seconds pass with no message, close the socket yourself, and the close handler reconnects and resumes:
With this rule in place, you can test reconnects by turning off Wi-Fi for 30 seconds during a game. The client closes the silent connection, retries with backoff until the network returns, then resumes from its last seq.
Handle stream errors
An error message that names a stream ends that subscription. The connection stays open, so for most codes you subscribe again:
In code, move the subscribe into a function so the handler can call it again:
Errors describes every code.
Stop on close codes that won’t recover
When the server closes the connection, the close code says whether reconnecting can help. For almost every code, back off, reconnect and resume. The exception is 1008, which means the key is invalid or revoked, or the account has no streaming access. Reconnecting won’t help until the key or plan changes:
4008 means the account already has as many connections as its plan allows. Backoff handles it, but if it keeps happening, close connections you don’t need. Errors lists every close code.
The whole client
follow.mts with all four rules
Without the stream
On Developer, or anywhere you can’t keep a WebSocket open, poll the changes feed. GET /v1/{league}/games/{id}/changes returns the same changes the stream sends, starting after the seq you pass, so the quickstart’s onChange works as is:
When lastSeq is behind head_seq, the loop requests the next page at once. Otherwise it waits five seconds. Each poll counts as one request against your allowance, so polling every five seconds uses about 720 requests per hour. The SDK retries rate_limited, internal and unavailable responses itself.
Replay a game
Subscribe with resume set to 0 and the stream sends the game’s whole journal from the first change. If the game is still going, live changes follow. Each replayed change counts as one request against your allowance, about 1,300 for a whole NFL game. To try a replay without a key, Sample responses feeds a recorded game through the same onChange.