Widgets and the launch Live Activity
Sunset Beach, NC ships one widget, named Sunset Beach in the widget gallery
(“The verdict, the next tide, and what’s worth walking out for.”), in four
sizes: home-screen small and medium, and lock-screen rectangular
and inline. Every size shows the overall beach score (the inline one
gives it up while an NWS alert is in force), and the larger ones add the verdict headline, the next tide, an active weather alert or rip
warning, surf height and the next almanac window. The widget reads the public
/api/summary endpoint about every 30 minutes and shows No data with a
reason if it cannot. Separately, a Live Activity counts down a visible
rocket launch on the Lock Screen and in the Dynamic Island for the hour before
liftoff.
What each widget size shows
Section titled “What each widget size shows”| Size | Shows | Tapping it opens |
|---|---|---|
| Small (home screen) | Score · verdict headline · one last line: an active NWS alert or rip warning if there is one, otherwise the next tide (High/Low and time) | Water if the last line is a tide, otherwise Today |
| Medium (home screen) | Left: score · headline · surf height. Right: the next two tides, the next almanac window (title, rating if scored, and how far away), and any alert or warning | Tide rows → Water; next window → When to go; anywhere else → Today |
| Rectangular (lock screen) | “Sunset Beach 88” · next tide (“Low 1:48 PM”) · third line: an NWS alert if in force, otherwise the next window (“Shelling in 2h 10m”) | Today |
| Inline (lock screen, beside the clock) | An NWS alert if in force; otherwise “88 · Low 1:48 PM”; otherwise “Beach 88” | Today |
Times are in the beach’s own time zone (Eastern).
Alerts outrank warnings. A National Weather Service alert (“Coastal Flood Warning”) is a public hazard notice; a warning (“Moderate rip current risk — …”) is the app’s own scoring advice. When both exist the alert wins, shown with a stop-sign octagon; when several alerts are in force the first is shown with a count, “Hurricane Force Wind Warning +2”. On the small widget a warning is shortened to its first clause. On the two lock-screen sizes only NWS alerts are shown, never warnings, and on the inline widget an alert displaces the tide entirely.
A clock icon beside the score means at least one of the sources behind the summary is a last known good copy rather than live data. See How fresh the data is.
An unscored window shows no rating. If the next almanac window’s rating is not meaningful for that occurrence, the widget prints its title and time without a rating word rather than inventing one.
How and when it refreshes
Section titled “How and when it refreshes”- The widget fetches
https://sunsetbeach.neuralconfig.com/api/summary— a roughly 1 KB payload built for it — with a 20-second timeout. It does not load the full conditions payload the app uses. - After a successful fetch it asks iOS to refresh again in 30 minutes; the Worker refreshes its sources every 5 minutes and nothing behind the summary is cached for less than 2 minutes, so refreshing faster would only re-read the same bytes. iOS treats the interval as a hint and may space refreshes further apart.
- After a failed fetch it retries in 10 minutes.
- The widget shows a single point in time, not a series of future entries — everything on it depends on a forecast or observation, so nothing is extrapolated between refreshes.
- Widget refreshes are independent of the app; the widget does not need the app to be open, and it always talks to the deployed Worker.
”No data” and the placeholder
Section titled “”No data” and the placeholder”| What you see | Meaning |
|---|---|
| No data with a wifi-exclamation icon (small and medium) — the medium size adds the reason underneath, e.g. “HTTP 503” or “The request timed out.” | The last fetch of /api/summary failed. It retries in 10 minutes. Check that the phone is online; if the app itself loads, the widget will recover on its next refresh. |
| ”Sunset Beach —” (rectangular) or “Beach —” (inline) | The same failure on a lock-screen size, which has no room for a reason. |
| A score of 88, “Go. Best for surfing.”, and a High tide at 3:29 AM | This is the fixed sample shown in the widget gallery and while iOS renders a placeholder; it is not live data. |
The launch Live Activity
Section titled “The launch Live Activity”When a rocket launch that the visibility model expects to be visible from the beach is within one hour before its scheduled liftoff (and up to 15 minutes after), the app starts a Live Activity: a countdown with the mission name on the Lock Screen, and a paper-plane glyph with the countdown in the Dynamic Island. Under the countdown it shows, in priority order:
- “Scrubbed — no launch tonight.” if the launch has been scrubbed;
- “Holding. <look direction>” if the launch is on hold;
- the look direction, e.g. “Good chance. Look SE. You’ll want a clear ocean horizon.”;
- otherwise “Visible from the beach.” or “Not expected to clear the horizon from here.”
The countdown ticks on the phone itself, so it stays right with no signal. What the phone cannot know — the launch time slipping, a hold, a scrub, or a launch going up — is pushed to the activity by the Worker, which checks every five minutes and sends only when something has actually changed. The activity ends and clears immediately when the launch flies, fails or is scrubbed, and iOS marks it out of date 15 minutes after the scheduled liftoff if nothing further arrives.
Two things to know:
- The app has to be open to start it. The activity is started when the app loads conditions (on launch and on every refresh) and finds a qualifying launch inside the window; the app targets iOS 17.0, which does not support starting an activity by push. Once started, updates arrive whether or not the app is open.
- Live Activities must be allowed for Sunset Beach in iOS Settings; if they are turned off the app silently does nothing.
The Live Activity is separate from the Visible rocket launches alert on the Alerts screen, which is a one-off local notification at your chosen lead time — see Alerts and notifications.