Skip to main content
Source: Home Widgets repository. Read its LICENSE before using or modifying the extension. This extension puts data from your web app into native home-screen widgets. It includes a stat card and a list with buttons and checkboxes. The page sets and reads the widget data, reloads the extension’s widgets, lists installed widgets and reads queued taps. It is for the Despia V3 runtime. You own and maintain the copied native code. First-party V4 support comes through the new package registry. Read V3 Extensions for build verification and rebuild requirements.

Install

  1. Copy the files below into public/despia/widgets/ in your web app, keeping their ios/ and android/ paths.
  2. Add "widgets" to the extensions array in public/despia/extensions.json, keeping your app identity and any other extension names.
  3. For iOS, register the App Group group.<your bundle id>.nx.widgets and enable it on both the app and the widget extension App IDs. The widget extension bundle ID is <your bundle id>.NXWidgets. Regenerate both provisioning profiles.
  4. Rebuild and install your native app with the extension compiled in. Changing native files requires fresh build verification and a new build.
The manifest adds the NXWidgets WidgetKit target on iOS and a custom Glance module on Android. The build policy stays with the trusted build inputs, outside your served public/despia/ folder. The Android module declares the widget receivers and its RemoteViews service.

Call it from your web app

Install the SDK with npm install despia-native. Import despia from despia-native and watch the route’s declared output variable. Call these functions from client events.
For live taps, register the declared onWidgetTap callback with browser lifecycle cleanup as described in Calling a route. Read taps after loading the page to recover queued taps. Setting data does not place a widget on the screen. The person adds it from the widget gallery, or accepts an Android pin request.

Routes and answers

Each success answer uses {ok: true, data: ...}. Failures use {ok: false, code, error}. The table lists the fields inside data. reload touches only this extension’s widget kinds. For installed, each iOS row contains template and family; each Android row contains template, width and height in dp.

Widget data

The JSON text must fit in 4096 UTF-8 bytes. Unknown keys, duplicate keys and invalid types return bad_data with the field path and reason. Each list item requires id and title (1 to 60 characters). It may have subtitle (1 to 60), checked (boolean) and link. Each button requires id and label (1 to 20). IDs contain 1 to 32 lowercase letters, digits, underscores or hyphens. IDs must be unique within their list or button array. tint is #RRGGBB. A link is an app path starting with one /, with no backslash or spaces, up to 512 characters.

Taps

onWidgetTap receives {seq, template, kind, id, at}, plus link for an open and checked for a toggle. kind is open, action or toggle. Its event scope is the document: pages that have called this extension receive it. Taps are stored before they are emitted. Call taps after a page loads, then pass the last consumed seq as ack on the next read to remove acknowledged taps. The queue keeps the newest 32 taps and counts older discarded taps in dropped.

Errors

Besides the standard bridge errors, the extension can return bad_data or storage_failed. On iOS, missing App Group access returns group_unavailable for the storage routes. Android pin can return pin_unavailable when the launcher does not support pinning. iOS pin returns platform_limit.

Platform limits

  • The iOS widget extension requires iOS 17. The user places widgets through the widget gallery; iOS has no app API for placing one. App Group access is required to share the widget data and taps.
  • Android pinning needs Android 8 or later and a launcher that supports it. requested: true confirms the request was shown, not that a widget was placed. Check installed afterwards.
  • Widget size, placement and update timing are controlled by the OS and launcher. The extension requests updates of its own widget kinds only.
  • Android widget taps may fail to open a link when the app is already running.
The extension skill includes a reference for this extension.

Files

Copy each file to its title’s path. The extensions.json block is an example for a new app; merge the extension name into your existing file rather than replacing its app identity.
public/despia/extensions.json
public/despia/widgets/manifest.json