Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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>
Name
Type
Required
Description

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 with user_gesture_required. Check permissions when you render the link: checking on click, before the call, spends the gesture.

  • They resolve null once 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 with request_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 showPage order.

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 showPage argument: getPages()[0] is opened by showPage(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.

Name
Type
Required
Description

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 through onError and 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, and isPageActionsSupported() is not authorization.

Example

Was this helpful?