Widgets

Push-driven iOS Home Screen, Lock Screen, and StandBy widgets. Declare a widget once, update its content with a PATCH, and the user's WidgetKit instances refresh automatically.

Widgets are persistent — once the user pins one to their Home Screen, Lock Screen, or StandBy, it stays there until they remove it. Use a widget for ambient state that should always be glanceable (a sensor reading, a server health indicator, a daily counter). For something that is currently happening and has a known end — a download, a timer, a print — reach for a Live Activity instead.

Templates

Five flat templates, each tuned for a different shape of data. Tap any card to jump to its content fields in the API reference.

value — Value

A single big number with optional unit, label, and trend arrow. Best for sensor readings and counters.

Required: value (number) + optional unit, label, trend

progress — Progress

A progress bar with label and accent color. Best for completion percentages and rollouts.

Required: value 0.0 – 1.0

status — Status

An iconic status pill driven by severity (info, warning, critical, success). No numbers — just state.

Required: severity (info, warning, critical, success)

gauge — Gauge

A needle gauge between a configurable min and max. Best for SLOs, error budgets, and capacity.

Required: value, min_value, max_value

stat_list — Stat list

Up to six label/value rows. Best for compact dashboards — MRR / Subs / Trials, Up / Down / Maintenance.

Required: stat_rows (array, 1 – 6 entries)

How it works

1. Your integration calls POST /widgets to declare a widget by slug, with a template and initial content.
2. The user opens the widget picker on their device and selects your slug for any system widget family they want — small, medium, large, accessory-rectangular, accessory-circular, or accessory-inline. The same slug can appear in multiple slots.
3. Your integration calls PATCH /widgets/{slug} whenever the underlying value changes. The server merges (RFC 7396) and pushes a thin update; the iOS widget extension reloads its timeline.
4. If a push is missed (background fetch coalescing, no network), iOS calls back into the extension every ~30 minutes for a freshness pull — GET /widgets/{slug} always returns the latest content.

Two ways to create widgets

Widgets don't require an integration to exist. There are two paths to the same backend, and both can target the same slug — a widget created in the app can later be driven by an integration, and vice versa.

• In the iOS app. Open the Widgets tab in PushWard, choose a template, and fill in the slug, name, and initial content. This is the right path for personal widgets — a temperature you key in by hand, a morale dial, a counter you bump from a Shortcut. The new slug appears immediately in the iOS widget picker for Home Screen, Lock Screen, and StandBy.
• Via the HTTP API. Use this when an external service should keep the widget content current — a homelab probe, a CI job, a smart-home automation. See the API reference.

Authentication

The widgets API is reachable two ways:

• An integration key (hlk_) with the widgets flag enabled. This is the right choice for third-party integrations — toggle the flag on the key in the iOS app's integration-keys screen.
• The user's full-access token (hla_), which the iOS app uses to manage its own widgets.

The iOS widget extension itself authenticates with a separate scoped token (hlw_) issued automatically by the app — integration authors never see or manage it.

Next steps

• Widgets API reference — endpoint shapes, content fields, and validation rules.
• Authentication — how to enable the widgets flag on an integration key.