Protocol
The request
The widget sends a GET request with details about the slot it needs to fill.
Use that information to return a layout that fits the phone and the widget size.
GET /widget?key=s3cret
&family=systemMedium
&w=338&h=158
&scale=3
&scheme=dark
&locale=en_GB
&tz=Europe/London
&v=1&rev=1
Host: you.example
Accept: */*
The widget keeps your own query parameters. If one of your parameters has the same name as
a parameter that the widget sends, the widget sends your value. You can therefore put a
token in ?key=….
What you receive
| Field | Type | Description |
|---|---|---|
family | string | systemSmall, systemMedium or systemLarge on the Home Screen. accessoryCircular, accessoryRectangular or accessoryInline on the Lock Screen. |
w | number | Slot width in points, for this phone. |
h | number | Slot height in points. |
scale | number | Screen scale, 2 or 3. Multiply by w and h for pixels. |
scheme | string | light or dark. This value is a hint. See the caveat on the request page. |
locale | string | The person's locale, such as en_GB. |
tz | string | IANA time zone, such as Europe/London. |
v | number | Protocol version the app speaks. |
rev | number | The revision of that version that the app understands. Send a node or field from a later revision only to an app whose rev is at least that revision. See versioning. |
Build for the slot
The three families need different layouts. A small is about 158 points square. A medium is
the same height and twice the width. A large is roughly square again at over twice the
height. Branch on family and send a layout made for that family.
app.get("/widget", (request, response) => {
const family = request.query.family;
// Answer with a layout that suits the slot rather than one that fits every slot.
const view = family === "systemSmall"
? compactView()
: detailedView();
response.json({ v: 1, view });
}); w and h are the exact size of the slot in points on that phone.
The size varies by screen. To render a bitmap, multiply by scale to get
pixels. See bitmap mode.
The widget is also available in the three Lock Screen sizes. family can
therefore be accessoryCircular, accessoryRectangular or
accessoryInline. These slots are much smaller than any Home Screen slot. iOS
always draws them in a vibrant mode with a single hue. This mode uses the same code path as
a tinted Home Screen: opaque backgrounds are dropped, and accentable keeps a
node in the bright group.
For a Lock Screen slot, return a few nodes, not the layout that you made for a medium. The previews on this site render only the three Home Screen families. Check a Lock Screen slot on a phone.
family to use the space.Do not rely on scheme alone
scheme is the appearance at the time of the fetch. WidgetKit renders one
timeline in both appearances. A payload fetched in light mode can still be on screen after
the phone changes to dark mode. The app does not fetch again when the appearance changes.
Semantic colour names do not have this problem. The
phone resolves them when it draws the widget, so "color": "primary" is correct
in both appearances. Use scheme to choose a palette. Use semantic names to
keep the widget readable. A bitmap cannot adapt to the appearance. This is the main reason
to use nodes and not a bitmap.
Tinted Home Screen
If the person sets the Home Screen to a tinted style, iOS discards most of the colour in a widget and redraws the widget in a single hue. The request does not describe this mode, because iOS chooses the mode each time it draws the widget. iOS draws one payload in every mode that it needs. When the person restyles the Home Screen, iOS redraws the payload that is already on the phone. The app does not fetch again.
The phone handles tinted mode. This has two effects on a payload. First, an opaque
background is dropped in these modes. If it stayed, the background would have the same hue
as the text on it, and the widget would look blank. Second,
accentable: true on a node keeps that node in the bright group and not the dim
group. Use it to keep a number legible when the colour is gone.
Inspect a real request
You cannot attach a debugger to a widget extension. To see the request that your phone sends, use the endpoint below as the URL of a widget. The widget shows the request that the phone sent.
https://webhookwidget.com/api/echo family. The medium shows the values in two columns. The small shows only the four rows that fit.Caching
The app caches responses on the phone and uses the cached response when a fetch fails. If a server is down for a short time, the widget shows the last good response with a small orange staleness dot, not an error. The app builds cache keys from the URL with any credentials removed.
For bitmap responses, Cache-Control: max-age is the
only way to ask for a refresh interval. A bitmap response has no envelope to contain
refresh.