Widget API and message protocol

The OpenDHelp object, the <opend-help-button> element, and the messages the panel and your page exchange.

The script

/embed/opend-help.js defines window.OpenDHelp and the opend-help-button custom element. It has no dependencies, can be loaded from any origin, and is cached for five minutes. Loading it twice is harmless.

OpenDHelp.init(options)

Call once before anything else; open throws until you do.

Option	Default	Meaning
`docsUrl`	required	Base URL of the docs site, such as `https://docs.example.com`. Messages are only accepted from, and sent to, its origin.
`app`	required	Your app's name, as in `resourceid appname`.
`getToken`	none	Returns a promise of a fresh embed token from your backend. Called whenever the panel has no session. If it rejects, the panel shows that sign-in failed.
`width`	`380`	Panel width in pixels. Screens narrower than 600 pixels get a full-width panel.
`side`	`'right'`	`'right'` or `'left'`.
`zIndex`	`2147483000`	Stacking order of the panel.
`onNavigate`	none	Called with `{ topicId, title }` whenever the panel shows a topic, for analytics or to remember the last topic.

Methods

A context is { key: 'tenants.detail' } or { path: '/tenants/acme' }.

Method	What it does
`open(context?)`	Opens the panel, on the given context or the last one set. Remembers which element had focus.
`close()`	Closes the panel and returns focus, even into shadow DOM.
`toggle(context?)`	Closes the panel if it is open, otherwise opens it.
`setContext(context)`	Records where the user is. Reloads the panel if it is open.
`isOpen()`	Whether the panel is open.

Escape closes the panel, whether focus is in your page or in the panel.

<opend-help-button>

Attribute	Meaning
`key`	Open this context key instead of the current context.
`path`	Open the context for this path.
`label`	Accessible name of the button. Default "Help for this page".

The button is a round "?" that inherits your text colour. Style it from outside with opend-help-button::part(button).

postMessage protocol

The panel is an iframe on the docs origin. It and the widget talk with window.postMessage. Every message is an object with protocol: 'opend-help' and v: 1 plus a type. Both sides check event.origin and event.source, and always send to an explicit origin, never *.

Type	Direction	Meaning
`opend:need-token`	panel to page	The panel has no session. The widget calls `getToken`.
`opend:token`	page to panel	`{ token }`: the embed token. The panel posts it to `/embed/session` and reloads.
`opend:ready`	panel to page	The panel has a session and has loaded.
`opend:navigated`	panel to page	`{ topicId, title }`: the panel shows a topic. Passed to `onNavigate`.
`opend:close`	panel to page	The reader closed the panel from inside it.
`opend:error`	panel to page	`{ message }`: the token exchange failed.

The panel only talks to the page when the page's origin is in the allowed origins: the widget passes its own origin to the panel's URL as host, and the server checks it. Opened anywhere else, the panel runs standalone and sends no messages.