Webhook Widget
Menu Bitmap mode

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.

Node
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 loseWhy 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

A server-drawn chart in a JSON view
json
{
  "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"
      }
    ]
  }
}
The sparkline is a PNG from the server. Everything else is text. The text scales with Dynamic Type, adapts to light and dark, and VoiceOver reads it.

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.