Run a Match from Your Smartwatch

If you referee or manage matches, you can run a whole game from your wrist — start the match, log goals, cards, fouls and substitutions, then end it — without taking the phone out of your pocket. This guide is the step-by-step companion to the Smartwatch Companion overview, focused purely on the live-match flow.

Before you start

The watch is a thin companion. It never talks to the 4league backend on its own — every tap on the wrist is relayed to the paired phone, which makes the real API call and sends the result back. Three things must be true before the live-match flow works:

• The phone is nearby and reachable — Bluetooth range, watch paired.
• The 4league phone app is running — open or backgrounded, but not force-quit. If it is killed, the relay is dead and the watch falls back to its waiting screen.
• The session has synced — on launch the phone pushes a SESSION_SYNC envelope to the watch. Until that arrives, the watch has no signed-in user and shows the waiting screen.

How a tap reaches the backend

Knowing the round-trip explains every "why isn't it working" case below. A single action — say, adding a goal — travels like this:

Add goal — the round trip
├── Watch — you tap a side / pick a scorer
├── Watch → Phone — ACTION_REQUEST (JSON on path /fourleague)
├── Phone → Backend — the real authenticated API call
├── Backend → Phone — result
└── Phone → Watch — ACTION_RESPONSE, the wrist UI updates

So if the watch seems to "hang" after an action, the break is almost always between the watch and the phone (out of range, app force-quit) or the phone and the backend (no connectivity) — not on the watch itself.

Step 1 — Open the match list

Step 2 — Run the match

From the live-match screen the full action set is available on Wear OS:

The two gestures to remember: tap the score for a goal, long-press for everything else (the ActionMenu). Each action waits for the phone's ACTION_RESPONSE before the wrist UI reflects it, so a brief spinner after a tap is normal.

Wear OS screen flow

Wear OS — live match
├── WaitingScreen — pre-session
├── MatchListScreen — near-term / in-progress matches you can edit
│   └── LiveMatchScreen — score, clock, Start / End
│       ├── GoalEntryScreen — tap score → pick scorer + assist
│       └── ActionMenuScreen — long-press
│           ├── CardEntryScreen — yellow / red
│           ├── FoulScreen
│           └── SubstitutionScreen
└── RankingsScreen — standings widget (all users, Wear OS only)

Wear OS vs. Apple Watch

Both companion apps exist — Wear OS (Kotlin / Jetpack Compose, under watches/wearos/) and watchOS (Swift / SwiftUI, under watches/watchos/) — and both share the same session handoff and the same "paired phone is the source of truth" model. The live-match action set, however, is only fully wired on Wear OS today.

On watchOS the only reachable flow today is WaitingView → MatchListView → a placeholder Text destination. The LiveMatchView, ActionMenuView and FoulView SwiftUI files exist in the source tree but are not attached to the navigation graph, and ActionMenuView references CardEntryView / SubstitutionView structs that aren't defined yet. So follow this guide on a Wear OS device for the full flow; on Apple Watch you can reach the match list but not yet run the game. The feature-parity table on the overview page tracks this.

Troubleshooting

For pairing, session sync and the rankings widget, see the full Smartwatch Companion page. For running matches from the phone, see Match Management.