Overlays
Introduction
The Maestro Web SDK supports overlays — short-lived, animated surfaces that the SDK renders on top of your page to deliver a timely message without interrupting playback. Where a panel is a persistent module the viewer opens and closes, an overlay appears on its own, plays an animation, and dismisses itself a few seconds later.
Overlays are authored and scheduled in the Maestro admin UI, not in code. Your application never renders one — it
implements a single delegate method, onOverlayEvent, and the SDK
handles the rest.
Your admin UI is at maestro.io.
Overview
Overlays are lightweight, animated UI components that the SDK mounts over your application to surface contextual moments — a settled bet, a fantasy player update, a promo. They support:
Rive animation for rich, resolution-independent motion
Auto-dismiss after a configured duration, with no host involvement
Call-to-action handling, including opening a Maestro panel when the viewer engages
Host-suggested positioning, so the overlay lands clear of your own UI
Optional D-pad focus, so remote users can navigate into the overlay and act on it
Overlays vs. Panels
Overlays and panels are both Maestro-rendered surfaces, but they behave very differently:
| Overlay | Panel | |
|---|---|---|
| Lifetime | Transient — appears, animates, and dismisses itself | Persistent — stays mounted until the viewer or host closes it |
| DOM container | The SDK creates and removes its own #maestro__sdk__overlay element | Your app provides the container and calls renderPanel() |
| Rendering | Rive animation on a WebGL2 canvas | React components rendered into the DOM |
| Trigger | A broadcast from Maestro, or a client-side rule evaluated by the SDK | The viewer navigating to the panel, or the host calling setActivePanel |
| Dismissal | An auto-dismiss timer, or viewer engagement | The viewer or the host |
| Focus | Opt-in per overlay via canFocus on the will-appear callback | The panel sidebar, via startFocusManagement |
Key Concepts
- Overlays are authored and scheduled in the Maestro admin UI. There is nothing to configure in code.
- There is no host-side feature flag for overlays on web. They are live as soon as a session starts. In practice,
enablement is (a) overlays and client rules configured for your page in the Maestro admin UI, and (b) your delegate
implementing
onOverlayEvent. - Overlays render with Rive, which requires WebGL2 and WebAssembly. On TV browsers that lack either, the SDK logs and renders nothing — overlays simply never appear. See Device & Browser Support.
- Ready to wire it up? Start with the Overlay Integration guide.
API reference
| Method | Description |
|---|---|
onOverlayEvent(event) | Delegate method that receives overlay lifecycle events |
setDataToOverlay(overlayData) | Push a new suggested position to a live overlay |
isOverlayShowing() | Check whether an overlay is currently on screen |