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].
session.input delivers the physical controls on the glasses and paired
controllers: button presses, touchpad gestures, keys, and the Meta Neural Band’s
air mouse. The starter scaffold wires a button press to the display, so a
short press shows a text wall.
src/background/index.ts
BUTTON hardware
requirement in your manifest to gate
the miniapp to those glasses.
Button presses
onButtonPress fires on every press of a physical button:
ButtonPressData has:
Keyboard
Even G2 glasses running Glassly CFW revision 39 or later can host a Bluetooth keyboard themselves (the user pairs it from the Glassly App under Controllers).onKey delivers every key transition to every subscribed
miniapp, the same way button presses are broadcast:
KeyboardEventData has:
A dropped link releases every held key with matching
up events, so a
modifier can never stay stuck. On glasses without a keyboard bridge the
subscription never fires.
The Meta Neural Band’s handwriting arrives through onKey too: each change to
the written text comes as down/up pairs that type it, with Backspace for
corrections and Enter for new lines. The band only listens for writing while a
miniapp has a text field open, so tell the host when yours is on the glasses:
catch.
Touch gestures
onTouch subscribes to touchpad gestures. Pass a handler for every gesture, a
single gesture name to filter, or an array of names for one subscription across
several gestures.
TouchData has:
The gesture values the runtime reports:
Glasses can send other
kind strings, so kind is typed as string. Match the
values you handle and ignore the rest.
Smooth scrolling on the ring
The R1 ring sends oneswipe_up / swipe_down per press, however far the
finger slides, like the temples. Reversing before the finger lifts sends no
second swipe. To scroll with the finger, subscribe to scroll_up /
scroll_down instead: one arrives for every step of travel during the slide,
the first included (it comes with the swipe), carrying distance and speed.
The direction follows the kind. Claiming a swipe does not claim its scroll
steps, so claim scroll_up / scroll_down too when only one app should see them.
One- and two-dimensional swipes
The G2 temples and the R1 ring swipe along one axis (swipe_up / swipe_down).
While any controller that swipes in two dimensions is connected (the Meta Neural
Band), session.capabilities.button.buttons includes an entry with
type: "swipe2d", and swipe_left / swipe_right arrive too.
The temples and the ring keep working while the band is connected, under the same
swipe_up / swipe_down names, so decide per gesture: the band’s touches carry
input2d: true. A game can steer in four absolute directions on the band and
fall back to relative turns on the temples; a menu can walk every item on a 1D
swipe and move by row or column on a 2D one:
Head position
Head position rides the touch stream:head_up and head_down are gestures
like any other, so they go through the claims. The
dashboard claims both while it runs; claim them yourself to receive them while
it is up. An unclaimed head_up on glasses that leave the dashboard to the
phone opens the glasses’ native dashboard.
session.imu.onHeadPosition is a
convenience over onTouch(["head_up", "head_down"], ...).
Air mouse
onPointer delivers the Meta Neural Band’s air mouse. Nothing arrives unless
the wearer turns on Air mouse in the Glassly App’s Neural Band settings.
PointerEventData has:
Claiming gestures
setClaimedGestures(gestures, {scope?}) registers the gestures your miniapp
handles. Claims stack: the most recent registration receives the gesture
alone, through onTouch, and the host skips its default behavior. This
also applies to background miniapps. Subscribing with onTouch alone does not
claim a gesture or override another miniapp’s claim.
scope uses the default
scope. Re-registering a nonempty set takes priority again. Use separate scopes
for persistent shortcuts and temporary pages so closing a page releases only
its claims. Stopping the miniapp releases every scope. onClaimChange reports
{gesture: string, held: boolean} to the miniapps gaining and losing a gesture;
a handoff between two scopes of the same miniapp does not fire it.
One host rule runs first: double-tap leaves a miniapp visibly drawing on the
main view if that miniapp has not registered double_tap in any scope. Claim it
if you use it while drawing there. Main content covered by a dashboard view
is not visible, so the rule does not exit the miniapp underneath. A main
miniapp that registered double-tap is not exited even if another claimant
currently has priority. The rule covers both of the Neural Band’s fingers. The
middle finger’s double tap (index: 1) skips the host’s other double-tap
defaults, and claims match it by name like the index finger’s.
Cleaning up
onButtonPress, onKey, onPointer, and every onTouch form return an
unsubscribe function:
onTouch with an array returns one unsubscribe function that drops all of
the gestures it registered.
