Navigation
Two kinds of navigation:
Native screens — the bound device's info screen, its timeline, and the organization's automations. Available on web and mobile.
Dashboard pages — pages configured as targets of this widget. Mobile only.
Open the device info screen
Opens the bound device's Device info screen.
bridge.openDeviceInfo() // → Promise<null>Parameters: none — passing any argument rejects with invalid_request.
If the widget is already shown inside the bound device's info screen, it switches to the info tab instead of opening a new screen.
Permission: VIEW_DEVICE_INFO.
Open the device timeline
Opens the bound device's Timeline screen, optionally at one event.
bridge.openDeviceEvents(options?) // → Promise<null>options.logEventId
string
no
DeviceEvent.id from getDeviceEvents() under the current binding. The screen scrolls to and highlights it
options must be a plain object with only logEventId. An unknown ID rejects with event_not_found.
Permission: VIEW_EVENTS.
Open automations
Opens the organization's Automations list (not filtered by device).
Parameters: none — passing any argument rejects with invalid_request.
Permission: VIEW_AUTOMATIONS.
Common rules for native screens
A user gesture is required. Call them directly from a click, tap or key-press handler — not after an
await, and not from a timer, a load handler or a value callback. Otherwise they reject withuser_gesture_required. Check permissions when you render the link: checking on click, before the call, spends the gesture.They resolve
nullonce the host has accepted the hand-off, not when the new screen finishes loading. The widget usually goes to the background right after.Web: one hand-off at a time. A second call while the previous one is still being handed off (about a second) rejects with
navigation_in_progress; a request with no answer rejects after 10 seconds withrequest_timeout.isPageActionsSupported()doesn't apply to them — feature-detect the method instead.
Rejects with invalid_request, user_gesture_required, navigation_in_progress, event_not_found, request_timeout, server_error, device_unavailable, bridge_destroyed.
Example
List dashboard pages (mobile only)
Returns the page targets configured on this widget, in
showPageorder.
The dashboard-page methods don't exist on web — bridge.getPages and bridge.showPage are undefined there, so an unguarded call throws a TypeError. Always gate on the capability flag and the method:
Resolves with only the page targets configured on this HTML Widget:
The array position is the
showPageargument:getPages()[0]is opened byshowPage(0).Pages of the template that aren't configured as targets of this widget never appear.
Duplicates are kept: a page configured twice appears twice, at both positions.
A target whose page can't be resolved keeps its slot with
name: ''.No targets configured, or no template available, gives
[].The list refreshes when the widget binding updates — rebuild navigation from a fresh read rather than caching it across reloads.
It isn't filtered by role or plan, so a listed target doesn't guarantee that navigation succeeds.
A page id is for display and bookkeeping — never pass it to showPage(). If you sort or filter the list for display, keep each entry's original position.
Open, close and leave dashboard pages (mobile only)
Opens a configured page target, closes the current page, or returns to the main dashboard.
index
number
yes
Position in getPages() — not a page id
There is no "page opened" callback. Give buttons a pressed state on
pointerdown; don't show a spinner that never resolves.A bad index — not an integer (
invalid_request), or outside the configured targets (index_out_of_bounds,details: { index, count }) — is reported throughonErrorand fails the call. Depending on the app, the failure is thrown synchronously or returned as a rejected Promise, so wrap the call to handle both.There is no page permission for
isPermissionAllowed, andisPageActionsSupported()is not authorization.
Example
Was this helpful?

