Triggering & Lifecycle

Triggering

Overlays reach a session in two ways, and both are configured in the Maestro admin UI rather than in your application.

Broadcast

An operator or an automated producer pushes an overlay to everyone watching. The overlay arrives with a triggerType.name of:

• BROADCAST — show the overlay as soon as it arrives.
• TIMECODED — show the overlay when playback reaches a specific timecode. This requires that your app feed playback position to the SDK with updatePlayerTimeCode. Without a timecode, the SDK has nothing to compare against and TIMECODED overlays never fire.

Client-side rules

Overlays can also be attached to client rules configured on the page. The SDK evaluates these rules locally against facts it tracks for the current session:

Fact	Meaning
time_in_session	Seconds elapsed since the session started
session_start	Fires once at the beginning of the session
panel_view	The viewer opened a panel
panel_engage	The viewer interacted with a panel

When a rule matches, the SDK raises the overlay exactly as it would a broadcast one — your delegate sees the same lifecycle events either way.

Lifecycle

Every overlay moves through the same sequence, delivered to your delegate through onOverlayEvent:

1. will-appear — the SDK is about to show the overlay and hands you a callback to approve it, request focus, and suggest a position. You have 2 seconds to call it. If you don't, the SDK applies its defaults (canAppear: true, canFocus: false) and shows the overlay anyway.
2. did-appear — the overlay is on screen and its animation has started.
3. did-engage (optional) — the viewer activated the call-to-action. The payload carries ctaType and ctaValue; for ctaType: 'show_panel', ctaValue is the panel to open.
4. did-dismiss — the overlay is gone and the SDK has cleaned up its container. Dismissal happens on engagement, or automatically after the overlay's configured durationSeconds — effectively durationSeconds ?? 5, so an overlay with no configured duration dismisses after 5 seconds.