Widget addons

Widgets are persistent web pages (alerts, goals, chat overlays). They are not tied to the overlay trigger queue.

Manifest

Direct URL

Always available when enabled:

http://localhost:{WEB_SERVER_PORT}/addon_static/{id}/?token={data.token}

Shown in settings as Widget URL for OBS Browser Source. The token query parameter is the addon frontend access token.

Static widget (no worker)

Only manifest.json, icon, HTML, and web_contents. Permission: WEB_CONTENT.

Full widget (worker)

Worker exposes HTTP or Socket.IO for live data; web page fetches from /addon/{id}/… or Socket.IO namespace.

Protect private endpoints:

if (query.token !== data.token) {
  return { error: 'Unauthorized' };
}

Display in overlay shell

App config widgets[] per installed widget:

Direct URL works regardless of display flags.

When the widget is embedded in the overlay shell, the iframe URL includes display=app (in-app overlay window) or display=web (common OBS overlay browser source). The direct Widget URL has token only — no display — so the page can detect the host:

const display = new URLSearchParams(window.location.search).get('display');
// null → opened by direct Widget URL
// 'app' → in-app overlay window
// 'web' → common OBS overlay link

Live sync: Socket.IO namespace /overlay, event widget:sync with { widgets: [{ widgetId, url }] }.

Snapshot: GET /widget/snapshot?display=app|web&token=

Settings UI

Settings → Widgets: install, enable, GenerateConfig fields, display checkboxes, copy widget URL.