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.

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, the SDK applies defaults after a timeout.
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.

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. Delaying or omitting the call may prevent the overlay from rendering correctly.
• 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.