Protocol
Bitmap mode
Return an image instead of JSON, and the image fills the widget. Use bitmap mode for content that is already an image. For other content, a JSON view is usually more flexible.
app.get("/widget.png", async (request, response) => {
// Render at the exact pixel size of the slot, or it will be resampled.
const width = Number(request.query.w) * Number(request.query.scale);
const height = Number(request.query.h) * Number(request.query.scale);
const png = await renderChart({ width, height, dark: request.query.scheme === "dark" });
response
.type("image/png")
// The only way a bitmap can ask for a refresh interval.
.set("Cache-Control", "max-age=1800")
.send(png);
});
Use w, h and scale from the request to render the
image at the pixel size of the widget. A bitmap at a different size is resampled, and
resampled text is not sharp on a Retina screen.
Trade-offs
An image cannot change between fetches, and it cannot resize itself. Live
timer nodes and Dynamic Type do not work in bitmap mode. You also lose the
three things in this table. Your server cannot work around any of them.
| You lose | Why your server cannot fix it |
|---|---|
| Light and dark |
iOS renders one timeline into both appearances and does not fetch again.
The scheme parameter is only a hint. A
bitmap fetched in light mode is also shown in dark mode. Tinted rendering is worse
for the same reason. A JSON payload gives iOS semantic nodes to recolour. A bitmap
gives iOS only pixels.
|
| The envelope fields | accessibility, url and entries are fields of
the JSON payload, and a bitmap has no JSON. The widget has a generic VoiceOver
label, no tap target and no timeline. Each fetch
gives one image.
|
| The refresh field | Cache-Control: max-age is the only way to ask for an interval. Without
it, the widget uses the default of 15 minutes.
|
Good uses for bitmap mode
- A map tile, a photograph or a camera snapshot. This content is already an image.
- A dense visualisation where every pixel is data and there is almost no text.
- A rendering pipeline that you already have and trust, if you would need to rewrite it to output nodes.
When only part of the widget is an image
{
"v": 1,
"preferredFamily": "systemMedium",
"refresh": 1800,
"accessibility": "Revenue today 8,240 pounds, up 12 percent on yesterday",
"url": "https://dashboard.example.com/revenue",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 0,
"padding": 14,
"bg": "#12141C",
"children": [
{
"type": "text",
"text": "REVENUE TODAY",
"style": "caption2",
"weight": "bold",
"color": "#6E7BA8"
},
{
"type": "hstack",
"spacing": 8,
"align": "center",
"children": [
{
"type": "text",
"text": "£8,240",
"style": "largeTitle",
"weight": "bold",
"design": "rounded",
"color": "white"
},
{
"type": "hstack",
"spacing": 2,
"padding": {"top": 3, "bottom": 3, "leading": 6, "trailing": 7},
"bg": "mint/20",
"corner": 8,
"children": [
{
"type": "symbol",
"name": "arrow.up.right",
"style": "caption",
"weight": "bold",
"color": "mint"
},
{
"type": "text",
"text": "12%",
"style": "subheadline",
"weight": "semibold",
"color": "mint"
}
]
}
]
},
{"type": "spacer"},
{
"type": "image",
"url": "https://webhookwidget.com/img/sparkline.png",
"fit": "fill",
"h": 46,
"tint": "mint"
}
]
}
} Limits
An image can be at most 2 MB and 2000 px on its longest side. An image node
has the same limits. The app checks both limits before it decodes the image, so it rejects
an oversized file without parsing it.