onOverlayEvent

Delivers overlay lifecycle events to the host application for handling.

Overview

onOverlayEvent is called whenever the Maestro overlay transitions between states — before appearing, after appearing, after user engagement, and after dismissal. Implement this method to control whether the overlay can appear, where it is positioned, and whether it should receive focus.

Implementing this method is all the host-side work overlays require — the SDK creates and removes its own container. For the full picture, see the Overlays section and the Overlay Integration guide.

Method Signature

onOverlayEvent(event: OverlayEvent): void;

Event types

Event type	Payload	Description
`will-appear`	`{ callback: (params: OverlayWillAppearEventCallbackParams) => void }`	The overlay is about to appear. Call `callback` to control visibility, focus, and position. If you do not call the callback within 2 seconds, the SDK applies its defaults and shows the overlay anyway.
`did-appear`	`null`	The overlay has appeared on screen.
`did-engage`	`{ ctaType: 'show_panel' \\| 'unknown'; ctaValue: string }`	The user interacted with the overlay call-to-action.
`did-dismiss`	`null`	The overlay has been dismissed.

`will-appear` callback parameters

When event.type === 'will-appear', call event.payload.callback with an OverlayWillAppearEventCallbackParams object:

Parameter	Type	Required	Default	Description
`canAppear`	`boolean`	No	`true`	Whether the overlay is allowed to appear. Set to `false` to suppress it.
`canFocus`	`boolean`	No	`false`	Whether the overlay should receive focus when it appears.
`suggestedPosition`	`{ x: number; y: number }`	No	SDK default	Suggested position in pixels. `x` is the offset from the right edge of the screen; `y` is the offset from the top.

All fields are optional. Omit any field to use the SDK default for that field.

2-second timeout

The SDK waits 2 seconds for the will-appear callback. If it has not been invoked by then, the SDK applies canAppear: true and canFocus: false and shows the overlay. This is deliberate — a delegate that hangs or misses a branch cannot silently suppress scheduled content. After the timeout elapses, calling the callback is a no-op, so answer synchronously rather than deferring the decision.

Return Value

This method does not return a value.

Example

import { IMaestroEventDelegate, OverlayEvent } from '@maestro_io/maestro-web-sdk';

class Delegate implements IMaestroEventDelegate {
  onOverlayEvent(event: OverlayEvent): void {
    switch (event.type) {
      case 'will-appear': {
        event.payload.callback({
          canAppear: true,
          canFocus: false,
          suggestedPosition: { x: 100, y: 50 },
        });
        break;
      }
      case 'did-appear': {
        console.log('Overlay appeared');
        break;
      }
      case 'did-engage': {
        console.log('Overlay CTA:', event.payload.ctaType, event.payload.ctaValue);
        break;
      }
      case 'did-dismiss': {
        console.log('Overlay dismissed');
        break;
      }
    }
  }
}

Notes

Always call the will-appear callback synchronously. The SDK waits 2 seconds and then falls back to its defaults, so a deferred call risks missing the window entirely — and past the timeout it has no effect, because the overlay has already been shown.
All OverlayWillAppearEventCallbackParams fields are optional. The SDK applies its configured defaults for any field you omit or if you never call the callback.
OverlayEvent is exported from @maestro_io/maestro-web-sdk and can be imported directly for use in typed switch statements.
Use isOverlayShowing to check whether the overlay is currently visible.
Use setDataToOverlay to push position data to the overlay programmatically.

onOverlayEvent

Overview​

Method Signature​

Event types​

will-appear callback parameters​

Return Value​

Example​

Notes​

See also​