Glassly Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.Developing on Mentra Live? We recommend using the
Glassly Bluetooth SDK.The developer tools are available in the Glassly App under Settings →
Miniapp Developer Settings.Share feedback with an in-app bug report, on
Discord, or by email at
[email protected].
miniapp.json and serve it from your background layer
with session.widgets.provide. The dashboard decides where the card goes and
how big it is. You draw into that box and push a new frame when your state
changes.
Declare a widget
miniapp.json
Declaring a widget needs no permission. The Store listing shows it.
Serve it
src/background/index.ts
provide takes the widget id and a set of optional hooks, and returns a handle.
It throws if you provide the same id twice. Call it as soon as your session
starts: a call that arrives before provide waits up to five seconds for it.
The box
The host assigns the box. When the widget is placed, and again whenever the wearer resizes it,onBox receives {size, width, height}: the size name and
the pixel extent of the card’s inner area. null means the widget was taken
off. Draw in box-local coordinates, where {x: 0, y: 0} is the top left of
your area. Do not assume a width or height beyond what onBox gave you; the
height varies with how the dashboard shares a column.
Push frames with update
update(elements) takes the same scene elements as session.display.render.
Call it whenever your state changes. The host keeps the latest frame per widget
and draws it, so you do not answer a render request and a closed dashboard costs
you nothing.
- At most one redraw per second reaches the glasses for each widget while the dashboard is open. Frames pushed faster are coalesced, and the latest wins.
- While the dashboard is closed, a frame only replaces the cached one.
- Keep a frame to 64 elements (128 for an expanded frame) and 256 KB at most.
- Elements outside the box are dropped.
Events and answers
The host sends youronEvent hook these events. The hook may be async. The
host waits a few seconds for an answer and then moves on.
Your widget is one stop in the dashboard’s selection order, like the built-in
cards. Swipes move the selection over it without telling you. A tap on it
activates it: from then on every swipe, tap and hold comes to you, until the wearer
double-taps, which deactivates it and leaves the dashboard open on your card.
A second double tap closes the dashboard. Wrap your highlight around at the
ends; there is no way to hand a swipe back.
Expand to the full screen
A widget does not have to expand. One withoutEX in its sizes keeps tap to
activate on its card, as above. List EX and a tap on the selected widget
expands it instead: the host gives it the full screen and sends
{type: "expand", width, height}. handle.expanded holds that box from then
on. Draw the expanded view in its local coordinates with
update(elements, {view: "expanded"}). Like an active card, an expanded widget
gets every swipe, tap and hold. A double tap sends {type: "collapse"} and
returns to the card, and so does closing the dashboard.
Expansion is optional for the wearer: the miniapp’s page in the Glassly App has
an “Open full screen” switch for each widget that lists EX, on by default.
With it off, a tap activates the card. Your miniapp can read and change the same
setting, for example from its own phone page:
EX. The dashboard reads the
setting each time it opens.
The host keeps the latest card frame and the latest expanded frame apart. An
expanded frame holds at most 128 elements. Expanded frames from a widget that
does not list EX are dropped.
Widget mode
A provider runs while at least one of its widgets is placed, and stops when none is. If you are placed, your miniapp runs headless in widget mode:- It is running, but has no card in the app switcher.
session.display.renderresolves{status: "blocked", reason: "widget mode"}. The glasses show the dashboard’s card, not your frame.- It receives no touch events, and its gesture claims are set aside.
- The Glassly App’s app switcher lists it under a Widgets pill. Tapping it opens the app.
session.miniapps.listreports it withrunning: false.
session.miniapps.start) promotes it to a normal run: display and touch work
as usual. Closing a placed miniapp from the tray, the Apps menu or a double tap
demotes it back to widget mode instead of stopping it. It stops when the wearer
removes its widgets or the dashboard stops.
Your widget code must not depend on having the display, so keep it separate
from the code that draws your own screens.
Limits
- The scene canvas is 576 by 288 pixels, and a widget draws into a part of it. The box is smaller than that, and a small card holds about two lines of text.
- The display is 4-bit grayscale: 16 gray levels.
- The builtin font is a fixed 20 px.
- The link to the glasses moves about 1 KB per second. Text is cheap, and images are not. Send art only when it changes, and do not animate anything you can redraw as text once a second.
- A tap travels from the glasses to the dashboard, to your miniapp, to your backend, and back as a frame. Draw the expected state at once and correct it when the answer arrives.
Host widgets
A dashboard places other miniapps’ widgets. This needs theHOST_WIDGETS
manifest permission, which has no OS prompt and is shown in the Store listing.
Its canonical key in session.permissions is hostWidgets. Without it, every
host call rejects with PERMISSION_NOT_DECLARED.
The host routes every call. A provider never learns which miniapp hosts it, and
a host never starts a provider by name. When a host stops or disconnects, the
engine drops its placements. See Build a dashboard
for the role itself.

