Reconnect Handling

Reconnect is explicit in v1 — the SDK does not retry automatically. This keeps the reconnection policy in your control and avoids surprise traffic during long idle periods.

Basic reconnect

// Reconnect closes the old socket, opens a new one, then syncs state.
await matchSession.reconnect()

reconnect():

1. Closes the current socket and detaches its listeners.
2. Opens a new socket with the same matchId and seatToken.
3. Waits for the normal welcome + first snapshot.
4. Sends an explicit syncRequest so the server resends state.

When to call it:

• The transport dropped (connectionState === 'closed' unexpectedly).
• The app woke from a long background pause.
• The user manually requested a reconnect.

Watch for drops

matchSession.on('connectionState', connectionState => {
  if (connectionState === 'closed') {
    // Add your own retry/backoff policy around this call in deployed apps.
    void matchSession.reconnect()
  }
})

Wrap this with a debounce, retry counter, and exponential backoff if you need to tolerate flapping networks.

Token invalidation

If the server rejects the seat token on reconnect, the handshake fails, reconnect() rejects with an Error, and connectionState becomes closed. In normal operation the token stays valid for the lifetime of the match, so token rejection usually means the match has ended or been evicted. Treat it as a terminal state and re-run the access flow (matches.create() / matches.join()) before trying again.

Preserved state

Across a successful reconnect the SDK keeps the last welcome and the latest snapshot it has seen. Listeners registered with on() are not detached. New snapshot and event values arriving after the reconnect flow through the same subscriptions.