Glance Widgets

Guides

Create a Custom Widget

Choose a size, design the appearance, add data and save.

  1. 1

    Create a widget

    Tap “+” in the top right of your widget library.

  2. 2

    Choose a size

    Choose Small, Medium or Large — they match Home Screen widget sizes exactly. Then tap “Create” in the top-right corner.

  3. 3

    Connect Your API (Optional)

    Paste your HTTPS URL into the API bar under the preview and tap refresh. The preview renders with live data right away.

    Good to knowThis step isn’t required. Leave it empty to design the look and layers first — you can still save, and come back once your backend is ready.

  4. 4

    Choose an appearance

    In the Widget panel, open “Material”, swipe through Liquid Glass, Glass, Solid Color, Gradient, Ambient Light or Image, then tap “Apply Style”.

  5. 5

    Add a Layer, Bind Data (Optional)

    Pick a layer such as Text or Curve under “Add Layer”. Set “Source” to “API Data” and enter a data path such as data.orders to show live values from your API.

    Good to knowThe data path can stay empty for now. The layer can still be added, edited and saved — bind it once your API is ready.

  6. 6

    Name it and save

    Name your widget and tap “Save”. It is now ready to add to your Home Screen.

Use Your Widget

Add the right widget to your Home Screen and select your design.

  1. 1

    Add to your Home Screen

    Hold an empty area on your Home Screen, tap “Edit”, then “Add Widget”.

  2. 2

    Match style and size

    Search for “Glance Widgets”, swipe to the style and size that match your widget, then tap “Add Widget”.

    Good to knowMatch the style and size of the custom widget you want to add: Liquid Glass widgets use “Liquid Glass”, Glass widgets use “Glass”, and Solid, Gradient, Ambient Light and Image widgets use “Basic”. Sizes must match too.

  3. 3

    Choose your widget

    Touch and hold the widget, tap “Edit Widget”, then choose the widget to show under “Widget”.

    Good to knowThe list only shows widgets whose size and style category match this one. If yours is missing, check its size and material in the app.

  4. 4

    Manage in the app

    Hold a library card or tap “…”. Refresh, duplicate, edit or delete it here; retry when a refresh fails.

Build & Connect an API

Connect your server, bind data or return a rendered image.

  1. 1

    Drive content and style with your API

    Your widget requests data from the API URL you set. Your server returns JSON following the protocol, letting the widget’s content and style change with your business.

  2. 2

    Use an SDK, or build it yourself

    The SDK simplifies API development and is optional. Use the official SDK to generate protocol data, or implement the API with your preferred language and framework. Either approach returns JSON that follows the same protocol.

  3. 3

    Adjust for devices when needed

    Size and position usually use relative values that adapt to the canvas. An API typically serves one particular widget, so separate size handling is usually unnecessary.

    Good to knowIf you display the same content on devices with slightly different screen sizes and notice rendering differences, you can use gw_canvas_width_pt / gw_canvas_height_pt from the request to make adjustments.

  4. 4

    Put business data in data

    The data field in your response holds business data that drives dynamic content, such as order counts, status and trends. Layers read it through paths like data.orders, so new business data updates the displayed content.

  5. 5

    Or display an image from your server

    Your server can take full control of drawing: generate the content, render it as an image and provide it dynamically through the API. Set the widget’s material to Image, its source to API and its image data path to display the finished image.

    Good to knowThis is an alternative approach: no Glance Widgets layers or detailed drawing syntax are needed. The API still returns JSON, with an image URL or Base64 string in data.

  6. 6

    Add request signing if you need it

    If you want to verify the request source, generate and copy an API signing secret in the editor and configure it on your server. Only the timestamp and signature are sent. Verify them yourself or use the SDK’s verifySignature.

  7. 7

    Preview right in the app

    You can preview your widget directly in the editor or the Home page’s library. The preview looks much like the widget on your Home Screen, so you can check it as you adjust content and style.

Set Up Widgets in StandBy

Set up a widget for the iPhone’s StandBy display.

  1. 1

    Meet StandBy

    When your locked iPhone is charging and turned on its side, it enters StandBy and shows clocks and widgets full screen. Put your widget here and read it at a glance from across the desk.

  2. 2

    Make sure it’s on

    StandBy needs iOS 17 or later and is on by default. If it never appears, open Settings › StandBy and make sure it’s turned on. It then starts whenever your iPhone is locked, charging and on its side.

  3. 3

    Add your widget

    In StandBy, touch and hold a widget and unlock with Face ID to start editing. Tap “+” in the top-left corner, find Glance Widgets, add the Small size, then tap “Done”. Choose which widget it shows just like on the Home Screen: touch and hold › “Edit Widget”.

  4. 4

    Look great in StandBy

    StandBy removes the widget background and enlarges the content. In a dark room, Night Mode tints everything red. High-contrast designs that still read well without a background work best.

    Good to knowWidgets with the Image material are specially handled: the image stays visible in StandBy and is never removed.